openapi: 3.2.0
info:
  title: Ledger Sell API
  version: '1.0'
  description: 'Operations tagged Sell across 2 of this provider''s published API definitions: ledger-card-provider-openapi.yml, ledger-sell-provider-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Sell
paths:
  /sell:
    post:
      operationId: postSell
      description: 'Generates a secure binary payload for the nano in order to authorize the transaction.

        - We send on sell endpoint the quoteId. 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/SellRequest'
      responses:
        '200':
          description: Sell 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/SellResponse'
              example:
                sellId: SELL-ID-165940
                amount: '1.337'
                payinAddress: '0xa0b86991c627e936c1d19d4a2e90a2ce3606eb48'
                createdAt: '2030-05-26T14:13:39'
                providerFees: '0.0001'
                referralFees: '0.0001'
                providerSig:
                  payload: CgUweGZmZhoFMHhmZmYqBTB4ZmZmOgNCVENCA0JBVEoIMTIwMDAwMDBSCDExNTAwMDAwWhF2ZXJ5IGxvbmd1ZSBub25jZQ==
                  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)
                SELL_QUOTE_NOT_FOUND_ERROR:
                  summary: SELL_QUOTE_NOT_FOUND_ERROR
                  value:
                    messageKey: SELL_QUOTE_NOT_FOUND_ERROR
                    message: When the sell 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 currencies is disabled in user's region. (you can add any useful field as you want)
      tags:
      - Sell
components:
  schemas:
    SellResponse:
      required:
      - sellId
      - payinAddress
      - createdAt
      - providerFees
      - referralFees
      - providerSig
      type: object
      properties:
        sellId:
          type: string
          description: 'provider''s id of the ongoing sell transaction. This will be used by Ledger''s backend to retrieve the status of user sell transaction. A unique id must be generated each time this endpoint is called, even if called with a same quoteId : quoteId != sellId. This is a sell 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 sell 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.
        providerSig:
          $ref: '#/components/schemas/ProviderSig'
    ErrorPayload:
      type: object
      required:
      - messageKey
      - message
      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.
    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.
    SellRequest:
      required:
      - quoteId
      - amount
      - refundAddress
      - fromCryptoCurrency
      - toFiatCurrency
      - payloadCryptoCurrency
      - nonce
      type: object
      properties:
        quoteId:
          type: string
          description: Previously generated quote ID.
        amount:
          type: string
          description: Amount requested by the user to be sold.
        refundAddress:
          type: string
          description: User's refund address, typically the fromAddress.
        fromCryptoCurrency:
          type: string
          description: From currency ID, using the provider's identifiers.
        toFiatCurrency:
          type: string
          description: Fiat currency at the ISO-4217 standard.
        payloadCryptoCurrency:
          type: string
          description: From currency ID, using Ledger's referential. (representing currency_from 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.
    ErrorPayload_2:
      type: object
      required:
      - message
      - messageKey
      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.
    SellRequest_2:
      required:
      - quoteId
      - amount
      - refundAddress
      - fromCryptoCurrency
      - toFiatCurrency
      - payloadCryptoCurrency
      - nonce
      type: object
      properties:
        quoteId:
          type: string
          description: Previously generated quote ID.
        amount:
          type: string
          description: Amount requested by the user to be sold.
        refundAddress:
          type: string
          description: User's refund address, typically the fromAddress.
        fromCryptoCurrency:
          type: string
          description: From currency ID, using the provider's identifiers.
        toFiatCurrency:
          type: string
          description: Fiat currency at the ISO-4217 standard.
        payloadCryptoCurrency:
          type: string
          description: The ticker of the currency the user wants to sell, as defined in Ledger’s referential (corresponding to currency_from in the protobuf payload). `BTC` or `ETH` for example. This ticker will be displayed on the Ledger device.
        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
x-refined-from:
- ledger-card-provider-openapi.yml
- ledger-sell-provider-openapi.yml