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"
}