openapi: 3.2.0
info:
  title: Partner Service Swap API
  version: '2.0'
tags:
- name: Swap
paths:
  /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)
      tags:
      - Swap
  /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)
      tags:
      - Swap
components:
  schemas:
    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.
    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'
    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.
    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.
    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.
  securitySchemes:
    defaultApiKey:
      type: apiKey
      name: x-api-key
      in: header