Provider’s Endpoints | Developers

Provider's Endpoints

Estimated reading time: 4 minutes

In order to communicate with Ledger’s back-end, you have to give us the mapping of the endpoints we need.
As you can see on the diagram What do we need?, there are 4 main endpoints needed for the swap:

  • To get the list of available currencies: /currencies.
  • To get the list of tradable pairs: /pairs.
  • To query a rate: /quote.
  • To query a swap status: /status.

You will find the details about each needed endpoint below.

GET /currencies

  • Function: Returns a list of supported currencies.
  • Input: –
  • Output: Array of supported currencies, with information required to uniquely identify coins/tokens.
  • Payload:
    [
    {
      "id":"BTC",
      "type":"coin",
      "blockchain":"bitcoin",
      "chainId":1
    },
    {
      "id":"USDC",
      "type":"token",
      "blockchain":"ethereum",
      "chainId":1,
      "contract":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
    ]
    

GET /pairs

  • Function: Returns a list of supported pairs. This endpoint is not required if all permutations returned by /currencies are supported.
  • Input: –
  • Output: Array of supported swap pairs, with supported quote type (fixed / float).
  • Payload:
    [
     {
        "from":"btc",
        "to":"bat",
        "tradeMethod":[
           "fixed",
           "float"
        ]
     },
     {
        "from":"bat",
        "to":"btc",
        "tradeMethod":[
           "fixed",
           "float"
        ]
     }
    ]
    

Fixed quote: The quote price is guaranteed until execution (or until end of quote validity period).
Float quote: The quote price is indicative only, real price is computed at execution time

POST /quote

  • Function: Returns a quote for a pair and amount.
  • Input:
    • from: currency id in your system.
    • to: currency id in your system.
    • amount: amount requested by the user, without the gas fee.
  • Output:
    • tradeMethod: fixed or float (optional, only required for consistency check)
    • quoteId: quote unique identifier (optional, only required for fixed quotes)
    • expiry: quote expiration timestamp (optional, only required for fixed quotes)
    • minAmountFrom: minimum valid amount for this pair (optional, only required if amount is too low)
    • maxAmountFrom: maximum valid amount for this pair (optional, only required if amount is too large)
    • amountFrom: should be same as amount (optional, only required for consistency check) (as an input coin floating amount)
    • amountTo: estimated output amount that will be sent to user (as an output coin floating amount)
    • payoutNetworkFees: estimated gas fees that will be used for the payout transaction (as an output coin floating amount)
  • Payload:
    • Success
      {
       "quoteId":"id1",
       "from":"btc",
       "to":"bat",
       "amountFrom":"1",
       "amountTo":"40000",
       "payoutNetworkFees": "0.0002",
       "rate":"37800.21",
       "tradeMethod":"float",
       "expiry": "date"  
      }
      

Note: the final estimated amount received by the user should be amountTo - payoutNetworkFees.

Some requirements about the /quote endpoint:

  • The quote must work without user auth. It can require a Ledger auth.
  • The quote must be valid long enough (at least a few minutes).

GET /status

  • Function: Returns the status of an executed swap transaction.
  • Input: swapId.
  • Output:
    • status:
      • FINISHED: Trade has been completed successfully (user has received payout transaction).
      • EXPIRED: Payin transaction was not received in time, trade is cancelled. User will be refunded if payin transaction is received afterwards.
      • ON_HOLD: Trade has been put on hold (eg: for KYC reasons). User must contact support.
      • PENDING: Trade is in progress (partner is waiting to receive payin transaction, or user is waiting to receive payout transaction)
      • REFUNDED: Trade has been cancelled, refund transaction has been successfully received by user.
      • UNKNOWN: Trade is in unknown state. User must contact support.
    • amount: as soon as this information is known, this should contain the final amount transferred to the user in output currency
    • payinTransactionId: as soon as this information is known, this should contain the payin transaction hash
    • payoutTransactionId: as soon as this information is known, this should contain the payout transaction hash
  • Payload:
    • Success
      {
       "quoteId":"id1",
       "status":"FINISHED",
       "amount": 1.337,
       "payinTransactionId": "0xfffffffffffff",
       "payoutTransactionId": "0xfffffffffffff"
      }
      

Did you find this page helpful?


How would you improve this page for developers?



What do we need?
Ledger's Endpoints
Getting Started
Theme Features
Customization

Swap