Sell integration architecture

The Sell integration exchanges data between Ledger Wallet, Ledger Backend, and the provider’s systems. To support the Sell feature in Ledger Wallet, providers implement specific endpoints and follow the workflow described below.

Workflow diagram

Opening the Sell app

Action: The user opens the Sell app in Ledger Wallet.

Ledger Wallet fetches capability data from Ledger Backend, which caches responses from the provider’s /capabilities endpoint. It also fetches the supported crypto assets from Ledger Backend, which caches responses from the provider’s /crypto-currencies endpoint.

User input and validation

User interaction: The user selects the crypto asset, fiat currency, and amount to sell.

The user then selects their country and preferred payment method, such as PayPal or a bank transfer.

Validation process: Ledger Wallet validates the input against cached data from /capabilities. The data includes provider limits, such as minimum and maximum amounts and supported countries.

If the input is invalid, Ledger Wallet displays an error message to the user.

Quotes and provider selection

User interaction: The user requests a quote.

Backend process: Ledger Backend identifies eligible providers based on the user’s input.

For each eligible provider, Ledger Backend sends a [GET] /quotes request to the provider backend. The response contains pricing details, such as the fiat amount the user will receive after fees.

Ledger Backend aggregates the returned quotes and displays them in Ledger Wallet.

User decision: The user selects a provider from the list of quotes.

Redirect to the provider widget

Action: After the user selects a provider, Ledger Wallet redirects them to the provider’s widget.

Redirection details: The redirect includes the parameters specified in the LiveApp URL documentation, such as the selected crypto asset, fiat currency, amount, and user details.

The user completes the transaction details in the provider widget.

Transaction initiation

Provider widget interaction: The provider widget starts the transaction by calling the exchangeSdk.sell method. This call triggers Ledger Backend to initiate the transaction.

Backend process: Ledger Backend sends a [POST] /sell request to the provider backend for a signed transaction payload.

The provider backend processes the request and returns the signed payload. Ledger Backend then passes the payload to the Exchange SDK.

Signer approval: The Exchange SDK prompts the Ledger signer to approve or reject the transaction.

The user approves or rejects the transaction on their Ledger signer.

Transaction finalization

After approval: When the transaction is approved, the exchangeSdk.sell promise sends the result to the provider widget. The result includes a transactionId for an approved transaction.

The provider widget then sends the final transaction status to the provider backend. If the user approved the transaction, the provider backend initiates webhooks.

If the user rejects the transaction, the provider is also notified.

Real-time updates

The provider backend sends real-time transaction status updates to Ledger Backend through the [POST] /webhook/status endpoint.

Ledger Backend updates the transaction status in Ledger Wallet so that the user can track its progress and completion.