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 currencypayinTransactionId: as soon as this information is known, this should contain the payin transaction hashpayoutTransactionId: 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"
}