openapi: 3.0.3 info: title: Partner Swap Service version: "2.0" paths: /currencies: get: operationId: getCryptoCurrencies description: | Return a paginated list of supported currencies. ⚠️ Please keep the currencies list static in the `/currencies` endpoint, unless you want to disable an asset for a longtime. parameters: - name: limit in: query required: false schema: type: integer format: int32 example: 10 - name: cursor in: query required: false schema: type: string example: "xxxxxxxx" responses: "200": description: | ### Available crypto currencies - "id": unique identifier of the currency - "type": possible values: coin, token - "blockchain": ledger's blockchain_name of the blockchain as listed in https://crypto-assets-service.api.ledger.com/v1/coins?output=blockchain_name,chain_id, for EVM networks this field may be omitted when chainId is defined. - "chainId": for EVMs only, chain id of the blockchain, 1 for ethereum, 137 for polygon... See https://chainlist.org/ - "contract": mapped only if type is token, the contract address of the token. blockchain OR chainId should be defined. If chainId is defined, blockchain field is ignored. x-summary: OK content: application/json: schema: type: object properties: currencies: type: array items: $ref: "#/components/schemas/CryptoCurrencies" next_cursor: type: string nullable: true description: Cursor to fetch the next page of results (null if no more results). example: currencies: - id: BTC type: coin blockchain: bitcoin - id: USDC type: token blockchain: ethereum chainId: 1 contract: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" next_cursor: "xxxxxxxx" /pairs: get: operationId: getPairs description: | Return a paginated list of supported pairs. ⚠️ If you are frequently disabling pairs, please keep the currencies list static in the `/currencies` endpoint, and only update pairs when necessary. parameters: - name: limit in: query required: false schema: type: integer format: int32 example: 10 - name: cursor in: query required: false schema: type: string example: "xxxxxxxx" responses: "200": description: Array of supported swap pairs. x-summary: OK content: application/json: schema: type: object properties: pairs: type: array items: $ref: "#/components/schemas/Pair" next_cursor: type: string nullable: true description: Cursor to fetch the next page of results (null if no more results). example: pairs: - from: btc to: bat tradeMethod: - fixed - float minSwapAmount: "0.00001" maxSwapAmount: "20" - from: bat to: btc tradeMethod: - fixed - float minSwapAmount: "5" maxSwapAmount: "10" next_cursor: "xxxxxxxx" /quote: post: operationId: postQuote description: | Return a quote for a pair and amount. - For fixed trade method, the quoteId is returned. requestBody: description: Information required for generating the payload. content: application/json: schema: $ref: "#/components/schemas/QuoteRequest" responses: "200": description: Successful quote response. x-summary: OK content: application/json: schema: $ref: "#/components/schemas/QuoteResponse" example: quoteId: "CC14E626-CF1B-4EDA-AF5E-766FFD5A3457" amount: "1" amountTo: "270.864632" providerFees: "0.0001" referralFees: "0.0001" payoutNetworkFees: "0.0002" tradeMethod: "float" expiry: "2022-04-04T09:10:51+0000" minAmountFrom: "1" maxAmountFrom: "3" defaultSlippage: "0.1" minSlippage: "0.1" maxSlippage: "0.3" "400": description: | This error indicates a violation of one or more constraints within the partner's system regarding the quote request. It is essential for the partner to specify the breached constraint to facilitate correction of the request. You can express any other constraints in your system by extending the error payload. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" examples: FROM_CURRENCY_MINIMUM_AMOUNT_ERROR: summary: FROM_CURRENCY_MINIMUM_AMOUNT_ERROR description: The amount of source currency is less that the minimum amount. value: messageKey: FROM_CURRENCY_MINIMUM_AMOUNT_ERROR message: Minimum error. (you can add any useful field as you want) additionalFields: minRequiredAmount: "0.01" maxRequiredAmount: "10" FROM_CURRENCY_MAXIMUM_AMOUNT_ERROR: summary: FROM_CURRENCY_MAXIMUM_AMOUNT_ERROR description: The amount of destination currency exceed the maximum amount. value: messageKey: FROM_CURRENCY_MAXIMUM_AMOUNT_ERROR message: Maximum error. (you can add any useful field as you want) additionalFields: minRequiredAmount: "0.01" maxRequiredAmount: "10" "404": description: The pair might be currently unavailable on your end, or you might not recognize one of the currencies. Please add relevant details about the causes. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" example: messageKey: SWAP_PAIR_NOT_FOUND_ERROR message: Swap pair not found. (you can add any useful field as you want) "451": description: User's IP address or currency is in a restricted region. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" examples: REGION_RESTRICTED_ERROR: summary: Region Restricted Error value: messageKey: REGION_RESTRICTED_ERROR message: User's IP address is in a restricted region. (you can add any useful field as you want) CURRENCY_REGION_RESTRICTED_ERROR: summary: Currency Region Restricted Error value: messageKey: CURRENCY_REGION_RESTRICTED_ERROR message: One of the swapped currencies is disabled in user's region. (you can add any useful field as you want) /swap/fixed: post: operationId: postSwapFixed description: | Generates a secure binary payload for the nano in order to authorize the transaction. - For swap with fixed trade method, we send on swap endpoint the quoteId (id generated with the previouse call to `/quote` ). The partner should retrieve the quote data (amounts…) from this id. - The final source of Truth for the user is the binary payload you generate. requestBody: description: Info for generating payload content: application/json: schema: $ref: "#/components/schemas/SwapRequestFixed" responses: "200": description: Swap ID with flattened JWS. `https://www.rfc-editor.org/rfc/rfc7515#section-7.2.2` x-summary: OK content: application/json: schema: $ref: "#/components/schemas/SwapResponse" example: swapId: "SWAP-ID-165940" payinAddress: "0xa0b86991c627e936c1d19d4a2e90a2ce3606eb48" createdAt: "2030-05-26T14:13:39" providerFees: "0.0001" referralFees: "0.0001" payoutNetworkFees: "0.0002" providerSig: payload: "CgUweGZmZhoFMHhmZmYqBTB4ZmZmOgNCVENCA0JBVEoIMTIwMDAwMDBSCDExNTAwMDAwWhF2ZXJ5IGxvbmd1ZSBub25jZQ==" payload_signature: "MEUCIBRm4PrdgRw0aBwRepuOGGRmR/YPcCoyKNJ7UDjFO030AiEA/VT0anolum0a3X/9lGPeovZHqzeDG9brcUB4zhYmwbs=" "400": description: Deposit wallet not available. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" example: messageKey: NO_DEPOSIT_WALLET_ERROR message: Deposit wallet not available. (you can add any useful field as you want) "404": description: Not found error. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" examples: CURRENCY_FROM_NOT_FOUND_ERROR: summary: CURRENCY_FROM_NOT_FOUND_ERROR value: messageKey: CURRENCY_FROM_NOT_FOUND_ERROR message: When the currency from is not found. (you can add any useful field as you want) CURRENCY_TO_NOT_FOUND_ERROR: summary: CURRENCY_TO_NOT_FOUND_ERROR value: messageKey: CURRENCY_TO_NOT_FOUND_ERROR message: When the currency to is not found. (you can add any useful field as you want) SWAP_QUOTE_NOT_FOUND_ERROR: summary: SWAP_QUOTE_NOT_FOUND_ERROR value: messageKey: SWAP_QUOTE_NOT_FOUND_ERROR message: When the swap quote is not found. (you can add any useful field as you want) "451": description: When the user's IP address is in a restricted region. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" examples: REGION_RESTRICTED_ERROR: summary: REGION_RESTRICTED_ERROR value: messageKey: REGION_RESTRICTED_ERROR message: User's IP address is in a restricted region. (you can add any useful field as you want) CURRENCY_REGION_RESTRICTED_ERROR: summary: CURRENCY_REGION_RESTRICTED_ERROR value: messageKey: CURRENCY_REGION_RESTRICTED_ERROR message: One of the swapped currencies is disabled in user's region. (you can add any useful field as you want) /swap/float: post: operationId: postSwapFloat description: | Generates a secure binary payload for the nano in order to authorize the transaction. - For swap with floating trade method, we send on swap endpoint the amount. This exact value should be used to generate the swap order and the binary payload, but the amount to might be updated. - The final source of Truth for the user is the binary payload you generate. requestBody: description: Info for generating payload content: application/json: schema: $ref: "#/components/schemas/SwapRequestFloat" responses: "200": description: Swap ID with flattened JWS. `https://www.rfc-editor.org/rfc/rfc7515#section-7.2.2` x-summary: OK content: application/json: schema: $ref: "#/components/schemas/SwapResponse" example: swapId: "SWAP-ID-165940" payinAddress: "0xa0b86991c627e936c1d19d4a2e90a2ce3606eb48" createdAt: "2030-05-26T14:13:39" providerFees: "0.0001" referralFees: "0.0001" payoutNetworkFees: "0.0002" providerSig: payload: "CgUweGZmZhoFMHhmZmYqBTB4ZmZmOgNCVENCA0JBVEoIMTIwMDAwMDBSCDExNTAwMDAwWhF2ZXJ5IGxvbmd1ZSBub25jZQ==" payload_signature: "MEUCIBRm4PrdgRw0aBwRepuOGGRmR/YPcCoyKNJ7UDjFO030AiEA/VT0anolum0a3X/9lGPeovZHqzeDG9brcUB4zhYmwbs=" "400": description: Deposit wallet not available. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" example: messageKey: NO_DEPOSIT_WALLET_ERROR message: Deposit wallet not available. (you can add any useful field as you want) "451": description: When the user's IP address is in a restricted region. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" examples: REGION_RESTRICTED_ERROR: summary: REGION_RESTRICTED_ERROR value: messageKey: REGION_RESTRICTED_ERROR message: User's IP address is in a restricted region. (you can add any useful field as you want) CURRENCY_REGION_RESTRICTED_ERROR: summary: CURRENCY_REGION_RESTRICTED_ERROR value: messageKey: CURRENCY_REGION_RESTRICTED_ERROR message: User's currency is in a restricted region. (you can add any useful field as you want) /status: get: operationId: getStatus description: Returns the status of a quote / trade being executed. parameters: - name: swapId in: query required: true schema: type: string example: 1234 responses: "200": description: Status of an executed swap transaction. x-summary: OK content: application/json: schema: $ref: "#/components/schemas/Status" example: status: "PENDING" amount: "1.337" payinTransactionId: "0xfffffffffffff" payoutTransactionId: "0xfffffffffffff" providerFees: "0.0001" referralFees: "0.0001" payoutNetworkFees: "0.0002" "404": description: Transaction not found. content: application/json: schema: $ref: "#/components/schemas/ErrorPayload" examples: TRANSACTION_NOT_FOUND: summary: Transaction not found value: message: "Provider error: Transaction with id 1234 does not exist." /webhook/{swapId}/status: post: operationId: statusUpdate description: | Real-time status webhook hosted by Ledger. Partners call this endpoint to notify Ledger whenever the status of a swap transaction changes. - Authenticated with the provider-specific `x-api-key` header (a shared secret provisioned by Ledger). Calls without a valid key are rejected with `401`, and the same `401` is returned for unknown / unsupported providers so callers cannot probe which providers exist. - Processing is asynchronous: a `200` means the update was authenticated, validated and queued, not that it has already been persisted. The update is applied shortly after, and only while the swap is still in a non-final status. - `providerStatus` is your own status string (typically the same value your `GET /status` endpoint returns). Ledger maps it to an internal status using the same per-provider mapping it uses when polling your `/status` endpoint; a value Ledger cannot map is rejected with `422` and nothing is persisted. parameters: - name: swapId in: path required: true description: The swap transaction id (the `swapId` returned by `/swap/fixed` or `/swap/float`). schema: type: string example: "SWAP-ID-165940" security: - defaultApiKey: [] requestBody: required: true description: Status update payload. content: application/json: schema: $ref: "#/components/schemas/StatusWebhookRequest" example: providerId: "moonpaytrade" providerStatus: "finished" amount: "0.1" providerFees: "0.001" networkFees: "0.0005" payinTransactionId: "0xabc123..." transactionHash: "0xdef456..." responses: "200": description: The status update was accepted and queued for asynchronous processing. x-summary: OK content: application/json: schema: $ref: "#/components/schemas/WebhookStatusQueued" example: message: queued "401": description: Missing or invalid `x-api-key`, or an unknown / unsupported provider (uniform and fail-closed). content: application/json: schema: $ref: "#/components/schemas/WebhookError" example: error: unauthorized "404": description: No swap matches the given `swapId` / `providerId`. content: application/json: schema: $ref: "#/components/schemas/WebhookError" example: error: transaction not found transactionId: "SWAP-ID-165940" "405": description: The swap is already in a final status and can no longer be updated. content: application/json: schema: $ref: "#/components/schemas/WebhookError" example: error: transaction can no longer be updated "422": description: The provided `providerStatus` is not recognized; nothing is persisted. content: application/json: schema: $ref: "#/components/schemas/WebhookError" example: error: unknown status "500": description: Unexpected error while processing the update. content: application/json: schema: $ref: "#/components/schemas/WebhookError" example: error: internal error components: securitySchemes: defaultApiKey: type: apiKey name: x-api-key in: header schemas: Coin: type: string CryptoCurrencies: required: - id - type - blockchain type: object properties: id: type: string type: $ref: "#/components/schemas/CryptoCurrencyType" blockchain: type: string chainId: type: integer format: int32 contract: type: string CryptoCurrencyType: oneOf: - $ref: "#/components/schemas/Coin" - $ref: "#/components/schemas/Token" Pair: required: - from - to - tradeMethod - minSwapAmount - maxSwapAmount type: object properties: from: description: source currency ID in the partner's system. type: string to: description: destination currency ID in the partner's system. type: string tradeMethod: type: array items: type: string enum: - fixed - float minSwapAmount: description: the minimum amount of the source currency that can be swapped. This is the lowest quantity of the initial currency that can be exchanged in a single transaction. type: string maxSwapAmount: description: the maximum amount of the source currency that can be swapped. This represents the highest quantity of the initial currency that can be exchanged in a single transaction. type: string QuoteRequest: required: - from - to - amount type: object properties: from: type: string description: Currency ID in the partner's system. example: "btc" to: type: string description: Currency ID in the partner's system. example: "eth" amount: type: string description: Or the amountTo, it's the amount that user will spend for the swap. (required only for float quotes) example: "1" SwapRequestFixed: required: - quoteId - refundAddress - payoutAddress - currencyFrom - currencyTo - payloadCurrencyFrom - payloadCurrencyTo - nonce type: object properties: quoteId: type: string description: Previously generated quote ID. refundAddress: type: string description: User's refund address, typically the fromAddress. payoutAddress: type: string description: User's payout transaction address. refundAddressExtraId: type: string description: Field used for blockchains that require a memo (e.g., XRP, XLM). payoutAddressExtraId: type: string description: Field used for blockchains that require a memo (e.g., XRP, XLM). currencyFrom: type: string description: From currency ID, using the provider's identifiers. currencyTo: type: string description: To currency ID, using the provider's identifiers. payloadCurrencyFrom: type: string description: From currency ID, using Ledger's referential. (representing currency_from in the protobuf payload) payloadCurrencyTo: type: string description: To currency ID, using Ledger's referential. (representing currency_to in the protobuf payload) nonce: type: string description: Value for the `device_transaction_id_ng` field in the protobuf payload, in hex format of the byte array nonce received by the user. slippage: type: string description: Value between 0 to 1 (0.1 => 10%). Maximum difference between the quoted amount and the final amount received, as a ratio. If exceeded, user consent is required or a refund is made. SwapRequestFloat: required: - amount - refundAddress - payoutAddress - currencyFrom - currencyTo - payloadCurrencyFrom - payloadCurrencyTo - nonce type: object properties: amount: type: string description: Amount requested by the user to be swap (or amountFrom). refundAddress: type: string description: User's refund address, typically the fromAddress. payoutAddress: type: string description: User's payout transaction address. refundAddressExtraId: type: string description: Field used for blockchains that require a memo (e.g., XRP, XLM). payoutAddressExtraId: type: string description: Field used for blockchains that require a memo (e.g., XRP, XLM). currencyFrom: type: string description: From currency ID, using the provider's identifiers. currencyTo: type: string description: To currency ID, using the provider's identifiers. payloadCurrencyFrom: type: string description: From currency ID, using Ledger's referential. (representing currency_from in the protobuf payload) payloadCurrencyTo: type: string description: To currency ID, using Ledger's referential. (representing currency_to in the protobuf payload) nonce: type: string description: Value for the `device_transaction_id_ng` field in the protobuf payload, in hex format of the byte array nonce received by the user. slippage: type: string description: Value between 0 to 1 (0.1 => 10%). Maximum difference between the quoted amount and the final amount received, as a ratio. If exceeded, user consent is required or a refund is made. ProviderSig: required: - payload - signature type: object properties: payload: type: string description: Protobuf payload (in binary format). signature: type: string description: Payload signed in JWS format. QuoteResponse: required: - amountTo - providerFees - referralFees - payoutNetworkFees - tradeMethod - expiry type: object properties: quoteId: type: string description: Unique identifier for the quote (Required only for fixed quotes). amount: type: string description: Should be the same as the input (optional, for consistency check). amountTo: type: string description: Estimated output amount sent to the user, in currencyTo. providerFees: type: string description: Amount paid to the provider, converted to currencyTo. referralFees: type: string description: Amount paid to Ledger, as a referral fee, converted to currencyTo. payoutNetworkFees: type: string description: Estimated gas fees for the payout transaction, converted to currencyTo. tradeMethod: type: string enum: - fixed - float description: Fixed or float expiry: type: string description: Quote expiration timestamp (required for fixed quotes) defaultSlippage: type: string description: Value between 0 to 1 (0.1 => 10%). Maximum difference between the amount the user has seen in his quote and the amount he might finally receive, as a ratio of the quoted amount. Otherwise, the user should be asked for his consent to the new trade or reimbursed in original coin. minSlippage: type: string description: Minimum allowable slippage. (0.1) maxSlippage: type: string description: Maximum allowable slippage. (0.3) ErrorPayload: type: object properties: messageKey: type: string description: Error code. message: type: string description: Error message description. additionalFields: type: object description: Provides further details on the error, including specific amounts involved in the request. All amounts are presented in their respective currency units. ServerError: required: - code - message type: object properties: code: type: integer format: int32 message: type: string Status: required: - status - amount - payinTransactionId - payoutTransactionId - providerFees - referralFees - payoutNetworkFees type: object properties: quoteId: type: string status: type: string enum: - FINISHED - EXPIRED - ON_HOLD - PENDING - REFUNDED - UNKNOWN amount: type: string description: as soon as this information is known, this should contain the final amount transferred to the user in output currency. payinTransactionId: type: string description: as soon as this information is known, this should contain the payin transaction hash. payoutTransactionId: type: string description: As soon as the transaction is submitted to the blockchain and the hash is generated, this field should contain the payout transaction hash. providerFees: type: string description: Fees paid to the provider. referralFees: type: string description: Fees paid to Ledger, as a referral fee. payoutNetworkFees: type: string description: Gas fees used for the payout transaction, converted to currencyTo. StatusWebhookRequest: required: - providerId - providerStatus - amount type: object properties: providerId: type: string description: Your provider id. Used by Ledger to authenticate the call and to select the status mapping; it must match the provider that owns the swap. example: "moonpaytrade" providerStatus: type: string description: Your own transaction status string, typically the same value returned by your `GET /status` endpoint. Ledger maps it to an internal status using the per-provider mapping; an unmapped value is rejected with `422`. example: "finished" amount: type: string description: Final amount transferred to the user, in the output currency. Required, because a finalized swap leaves the polling set and a missing amount would never be backfilled. providerFees: type: string description: Fees paid to the provider, converted to the output currency. networkFees: type: string description: Referral / extra fee, converted to the output currency. payinTransactionId: type: string description: On-chain payin transaction hash. transactionHash: type: string description: On-chain payout transaction hash. WebhookStatusQueued: required: - message type: object properties: message: type: string description: Always `queued` - the update was accepted and will be applied asynchronously. example: queued WebhookError: required: - error type: object properties: error: type: string description: Human-readable error reason. transactionId: type: string description: The `swapId` from the request path. Present only on `404` responses. SwapResponse: required: - swapId - payinAddress - createdAt - providerFees - referralFees - payoutNetworkFees - providerSig type: object properties: swapId: type: string description: "provider's id of the ongoing swap transaction. This will be used by Ledger's backend to retrieve the status of user swap transaction. A unique id must be generated each time this endpoint is called, even if called with a same quoteId : quoteId != swapId. This is a swap attempt id and several retries sharing the same quote id might be performed by a user." payinAddress: type: string description: Provider's payin address. createdAt: type: string description: Creation date of the swap payload in ISO-8601 format. providerFees: type: string description: Fees paid to the provider, converted to currencyTo. referralFees: type: string description: Fees paid to Ledger, as a referral fee, converted to currencyTo. payoutNetworkFees: type: string description: estimated gas fees that will be used for the payout transaction (as an output coin floating amount). providerSig: $ref: "#/components/schemas/ProviderSig" Token: type: string