Fund Express wallets

This guide explains how to debit funds from your fiat account and credit them to your customer's stablecoin account. To complete the conversion, you will need the recipient's stablecoin wallet ID, which you can obtain using the get wallets endpoint.

The Embedded Express product follows a straightforward process:

Get wallet ID: Retrieve the customer's stablecoin wallet ID using the get wallets endpoint.
Create a transfer with a quote: Create a transfer from your fiat wallet to the customer's stablecoin wallet with the QUOTE conversion type.
Accept quote: Accept the quote to execute the conversion. This action debits your fiat account and credits the customer's stablecoin wallet.

Once complete, the converted stablecoins are stored in the customer's wallet and available for future transactions.

Prerequisites

Before initiating the transfer, ensure you have the following:

A fiat wallet with a sufficient balance, and its wallet ID
The customerReference for the end user whose stablecoin wallet you intend to credit
API credentials with merchant-level permissions

You do not need to create a wallet for Express customers. USDC wallets are automatically created when customers log into the Express app for the first time.

Get wallets

To obtain the wallet ID for the end user's stablecoin account, use the GET /ledger/v1/wallets endpoint.

Filter wallets by customerReference to locate a specific customer's wallets and by currencyCode to find wallets in a particular currency, such as USDC or USDT.

GET /ledger/v1/wallets?customerReference=33e85982-e22b-4e8b-9057-445cf000bea9&currencyCode=USDC

The response provides a list of wallets and their details:

{
  "content": [
    {
      "id": "a:24092328494070:G5i4XZ9:1",
      "accountReference": "4488d086-f2c2-5bdf-0b01-7dgcedfbfbb0",
      "customerReference": "33e85982-e22b-4e8b-9057-445cf000bea9",
      "name": "USDC Crypto Wallet",
      "status": "ACTIVE",
      "balance": {
        "value": 250.00,
        "currencyCode": "USDC"
      },
      "ledgers": [
        {
          "type": "CRYPTO",
          "address": "0x1234567890abcdef1234567890abcdef12345678",
          "network": "ETHEREUM"
        }
      ],
      "capabilities": "SAFEGUARDED"
    }
  ],
  ...
}

Find the id field in the response. This is the wallet ID required for the transfer.

Fund wallet

Create a transfer from your fiat wallet to the customer's stablecoin wallet by sending a POST request to /payment/v3/transfers with the QUOTE conversion type. Include a unique Idempotency-Key header so that a retry does not create the transfer twice.

Request
{
  "reference": "REF6435921392",
  "originator": {
    "amount": 100,
    "currency": "USD",
    "walletId": "a:26012726855253:zMpcRHg:1"
  },
  "beneficiary": {
    "currency": "USDC",
    "walletId": "a:24092328494070:G5i4XZ9:1"
  },
  "conversion": {
    "type": "QUOTE",
    "validityDuration": "PT20S"
  },
  "metadata": {}
}

The transfer is created in PENDING_QUOTE_ACCEPTANCE status. The response contains the quoted rate, the fees, and the digest that you need to accept the quote.

Example Response
{
  "id": "7c1f5e2a-3b9d-4e68-a1c4-5d0b8e92f6a3",
  "reference": "REF6435921392",
  "type": "payment:transfer",
  "status": "PENDING_QUOTE_ACCEPTANCE",
  "metadata": {},
  "fees": {
    "processingFee": {
      "amount": 0.25,
      "currency": "USD"
    }
  },
  "originator": {
    "amount": 100,
    "currency": "USD",
    "walletId": "a:26012726855253:zMpcRHg:1"
  },
  "beneficiary": {
    "amount": 99.85,
    "currency": "USDC",
    "walletId": "a:24092328494070:G5i4XZ9:1"
  },
  "conversion": {
    "type": "QUOTE",
    "spread": {
      "percentage": 0.001,
      "amount": 0.1,
      "currency": "USD"
    },
    "allInRate": 0.9985,
    "baseRate": 0.9995,
    "validityDuration": "PT20S",
    "expiresAt": "2026-10-29T10:00:20Z",
    "digest": "f3a9c1d7b2e4"
  },
  "expiresAt": "2026-10-30T10:00:00Z",
  "createdAt": "2026-10-29T10:00:00Z",
  "updatedAt": "2026-10-29T10:00:00Z",
  "trackingDetails": [],
  "method": "BOOK"
}

note

Many customers prefer a one-step flow rather than creating a quote and then accepting it separately. To skip the acceptance step, set conversion.type to AUTO_CONVERSION. The transfer then executes at the market rate immediately. For details, see Conversion transfer with auto conversion.

Accept the quote before it expires by sending a POST request to /payment/v3/transfers/{transferId}/actions with the digest from the previous response. If the quote expires first, refresh it as described in Refresh an expired quote.
Request
```
{
  "type": "ACCEPT_QUOTE",
  "digest": "f3a9c1d7b2e4"
}
```
warning
You may choose whether or not to display the rate to your customers, but you must not present it as a guaranteed rate. The rate must be shown as indicative only, reflecting the nature of the service BVNK provides to that user.

After you accept the quote, the transfer moves to PROCESSING, and the stablecoins are credited to the customer's wallet once it completes. Track the transfer by sending a GET request to /payment/v3/transfers/{transferId}, or subscribe to the Transfer webhook.

Get wallet balance

For the best user experience, we recommend implementing functionality to retrieve wallet balances. Integrate the Get Wallet or List Wallet Balances endpoints to display real-time balances to users on your platform.

This allows users to:

View the current balances of their wallets (including available and pending amounts).
Confirm that funds have arrived before starting transfers or conversions.
Track their assets across multiple currencies or wallets.
Increase trust and transparency in your application.

Receive notifications

Use the Webhooks feature to receive notifications about wallet balance changes.

When the wallet balance changes, you will receive a webhook notification with the following details:

The wallet ID
The new balance
The currency
The timestamp
The transaction ID

Prerequisites​

Get wallets​

Fund wallet​

Get wallet balance​

Receive notifications​

Prerequisites

Get wallets

Fund wallet

Get wallet balance

Receive notifications