Wallet to Wallet internal swap

POST {{base_url}}/api/v1/user/wallet/swap

Swap funds between supported currencies within a user's LedgerBlock wallet.

An internal swap is modeled around three core concepts:

Base Currency (from_currency) — the currency being paid or debited from the source wallet.
Quote Currency (to_currency) — the currency the user receives after the swap.
Swap Rate (rate_used) — the prevailing exchange rate applied to the transaction.

Unlike an external swap, an internal swap does not require an external beneficiary account. The funds are debited from the user's source wallet and the converted amount is credited to the corresponding wallet in the destination currency.

How It Works

The merchant submits a swap request specifying the source wallet, destination currency, amount, and transaction reference.
LedgerBlock validates the request and calculates the conversion using the prevailing swap rate.
LedgerBlock initializes the swap and returns an auth_token.
The user confirms the transaction using their wallet PIN.
Once successfully authorized, the source currency is debited and the converted amount is credited in the destination currency.
The transaction status can be communicated through the configured notification_url.

Important: Initializing the swap does not complete the transaction. The user must confirm the swap with their wallet PIN before the transaction is completed.

Request

Headers

Use the standard LedgerBlock authentication headers.

Content-Type: application/json
Authorization: Bearer {{secret_key}}

Request Body

{
  "user_ref": "{{merchant_user_ref}}",
  "source_wallet_id": "LBWCADFAE7405062AC4815B971F6DEB0F1EE0200DKT",
  "to_currency": "NGN",
  "amount": 1,
  "txn_ref": "sw_000001",
  "notification_url": "https://webhook.site"
}

Request Parameters

Parameter	Type	Required	Description
`user_ref`	string	Yes	The merchant's reference for the LedgerBlock user initiating the swap.
`source_wallet_id`	string	Yes	The ID of the wallet from which the source currency will be debited.
`to_currency`	string	Yes	The destination currency the user wants to receive.
`amount`	number	Yes	The amount of the source currency to swap.
`txn_ref`	string	Yes	A unique transaction reference generated by the merchant.
`notification_url`	string	Yes	The URL LedgerBlock uses to send transaction status notifications.

Currency Flow

The swap follows this structure:

Source Wallet → Base Currency → Swap Rate → Destination Currency

For example, if the source wallet contains CAD and the user requests NGN:

CAD 1
   ↓
Swap Rate: 972
   ↓
NGN 972

In this example:

Base/Source Currency: CAD
Quote/Destination Currency: NGN
Amount: 1 CAD
Rate: 972
Converted Amount: 972 NGN

Response

A successful initialization returns the payment reference, currencies involved, conversion rate, converted amount, and authorization token.

{
  "status": "success",
  "message": "Swap initialized. Confirm with your wallet PIN to complete it",
  "data": {
    "payment_ref": "dc843631-87ac-45ad-b438-d6d732882eea",
    "txn_ref": "sw_000001",
    "from_currency": "CAD",
    "to_currency": "NGN",
    "amount": 1,
    "converted_amount": 972,
    "rate_used": 972,
    "auth_token": "a4cd4dcefeb436a538e56f1a8d8b63d778d1c43b89cf065244bdddf1a068aeb5",
    "expires_in_seconds": 600
  }
}

Response Parameters

Parameter	Type	Description
`status`	string	Indicates whether the swap initialization was successful.
`message`	string	Describes the result of the request.
`payment_ref`	string	Unique reference generated by LedgerBlock for the swap payment/authorization flow.
`txn_ref`	string	The merchant-provided transaction reference.
`from_currency`	string	The source currency being debited from the wallet.
`to_currency`	string	The destination currency being credited to the user.
`amount`	number	Amount of the source currency being swapped.
`converted_amount`	number	Amount of the destination currency the user will receive based on the applied rate.
`rate_used`	number	Exchange rate applied to the swap.
`auth_token`	string	Token used to authorize/confirm the swap with the user's wallet PIN.
`expires_in_seconds`	number	Number of seconds before the authorization token expires.

PIN Confirmation

The swap remains in an initialized state until the user confirms it with their wallet PIN.

The auth_token returned in the initialization response is associated with this authorization step and expires after the period specified by expires_in_seconds.

In the example above, the authorization expires after 600 seconds (10 minutes).

If the user does not confirm the swap within the validity period, the authorization expires and a new swap request may be required.

Example Transaction

A user wants to convert 1 CAD to NGN.

The request specifies:

Source Wallet: CAD Wallet
Destination Currency: NGN
Amount: 1 CAD
Swap Rate: 972

LedgerBlock initializes the transaction and returns:

1 CAD × 972 = 972 NGN

After the user successfully confirms the transaction with their wallet PIN:

CAD Wallet
- 1 CAD

        ↓ SWAP

NGN Wallet
+ 972 NGN

The swap therefore moves value between the user's supported currency wallets without requiring an external payout beneficiary.