api-docs.yml

openapi: '3.0.2'
info:
  title: LndHubX  
  version: '1.0 Alpha'
  description: | 
   LndhubX is a Lightning Bitcoin bank that allows users to swap into synthetic fiat and back.

   Learn more about the project on Github: https://github.com/kolliderhq/lndhubx

servers:
  - url: https://lndhubx.kollider.xyz/api
paths:
  /nodeinfo:
    get:
      summary: Info about Lndhubx.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankInfo'
  /create:
    post:
      summary: Creates a new user.
      requestBody:
        description: This creates a new unique user on LndhubX.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/requestBodies/CreateUser'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /auth:
    post:
      summary: Logs in a new user.
      requestBody:
        description: This will log a user and in an return the JWT tokens.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/requestBodies/CreateUser'
      responses:
        '200':
          description: Returns an object of accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Auth'

  /balance:
    get:
      summary: Get user balance.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balances'
  /addinvoice:
    get:
      summary: Creates a new invoice.
      parameters:
        - in: query
          name: amount
          schema:
            type: integer
          required: true
          description: The amount of the specified currency. NOTE BTC is not denominated in Sats but in BTC.
        - in: query
          name: currency 
          schema:
            type: string 
          required: false
          description: The currency you want to deposit.
        - in: query
          name: meta 
          schema:
            type: string 
          required: false
          description: Some optional meta data to include in the invoice.
        - in: query
          name: account_id
          schema:
            type: string 
          required: false
          description: If you want to generate the invoice for a specific account otherwise your default account is used.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddInvoice'
  /payinvoice:
    post:
      summary: Pay an invoice.
      requestBody:
        description: This will pay an invoice. Internal payments are possible but no self payments.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/requestBodies/PayInvoice'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayInvoice'
  /getuserinvoices:
    get:
      summary: Gets all invoices that were generated by user.
      responses:
        '200':
          description: OK
  /getavailablecurrencies:
    get:
      summary: Shows you all available currencies to swap into.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /swap:
    post:
      summary: Swap one currency for another.
      requestBody:
        description: This will swap any two currencies with each other.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/requestBodies/Swap'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
  /quote:
    get:
      summary: Get a quote for a currency swap.
      parameters:
        - in: query
          name: from_currency
          schema:
            type: string 
          required: true
          description: The currency you want to sell.
        - in: query
          name: to_currency
          schema:
            type: string 
          required: true
          description: The currency you want to buy.
        - in: query
          name: amount
          schema:
            type: integer
          required: true
          description: The amount you want to swap. Note BTC is denominated in BTC not Sats.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
  /gettxs:
    get:
      summary: Gets all transactions made by user.
      description: This includes deposits, withdrawals and swaps.
      responses:
        '200':
          description: OK

  /checkpayment:
    get:
      summary: Lets you check the status of a payment.
      parameters:
        - in: query
          name: payment_hash
          schema:
            type: string 
          required: true
          description: The payment hash of the payment you would like to get the status of.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckPaymentResponse'

  /get_onchain_address:
    get:
      summary: Gets an BTC on-chain deposit address.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOnchainAddressResponse'

  /make_onchain_swap:
    post:
      summary: This allows you to send lightning bitcoin to an onchain address.
      requestBody:
        description: Lightning to onchain Bitcoin.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/requestBodies/OnchainSwapRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnchainSwapResponse'

  /lnurl_withdrawal/create:
    get:
      summary: Create an lnurl withdrawal request.
      parameters:
        - in: query
          name: amount 
          schema:
            type: integer 
          required: true
          description: The amount of the withdrawal request.
        - in: query
          name: currency
          schema:
            type: string 
          required: true
          description: The currency you want to withdrawal (BTC, USD, EUR).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLnurlWithdrawalRequest'

components:
  schemas:
    Balances:
      type: object
      properties:
        account_id:
          type: string 
        account_type:
          type: string 
        balance:
          type: integer 
        currency:
          type: string
    User:
      type: object
      properties:
        username:
          type: string 
    Auth:
      type: object
      properties:
        access_token:
          type: string 
        refresh_token:
          type: string
    AddInvoice:
      type: object
      properties:
        payment_request:
          type: string 
        amount:
          type: string
        account_id:
          type: string
        meta:
          type: string
        rate:
          type: string
        currency:
          type: string
    Quote:
      type: object
      properties:
        amount:
          type: string 
        from:
          type: string
        to:
          type: string
        valid_until:
          type: integer
        rate:
          type: string
        quote_id:
          type: integer
        error:
          type: string

    CheckPaymentResponse:
      type: object
      properties:
        paid:
          type: bool

    GetOnchainAddressResponse:
      type: object
      properties:
        address:
          type: string
        commitment:
          type: string 
        signature:
          type: string
        secret_access_key:
          type: string

    OnchainSwapResponse:
      type: object
      properties:
        bolt11_invoice:
          type: string 
        fees_sats:
          type: integer 

    Swap:
      type: object
      properties:
        success:
          type: boolean
        amount:
          type: string 
        from:
          type: string
        to:
          type: string
        rate:
          type: string
        error:
          type: string

    PayInvoice:
      type: object
      properties:
        success:
          type: boolean
        currency:
          type: string
        payment_request:
          type: string
        fee:
          type: string
        error:
          type: string
    BankInfo:
      type: object
      properties:
        ln_network_max_fee:
          type: string 
        ln_network_fee_margin:
          type: string
        reserve_ratio:
          type: string
        external_tx_fee:
          type: string
        internal_tx_fee:
          type: string

    CreateLnurlWithdrawalRequest:
      type: object
      properties:
        lnurl: string
      
  requestBodies:
    CreateUser:
      type: object
      properties:
        username:
          type: string
          description: A unique username.
        password:
          type: string
          description: A unique strong password.
    PayInvoice:
      type: object
      properties:
        payment_request:
          type: string
          description: The LN payment request to be paid.
    Swap:
      type: object
      properties:
        from_currency:
          type: string
          description: The currency you want to sell.
        to_currency:
          type: string
          description: The currency you wan to buy.
        amount:
          type: string
          description: The amount you want to swap.

    OnchainSwapRequest:
      type: object
      properties:
        amount_sats:
          type: integer 
        onchain_address:
          type: string 
        onchain_sats_per_vbyte:
          type: integer