Fund Express wallets

• Embedded model
• Express model
• Fiat
• Stablecoin

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:

1. Get wallet ID: Retrieve the customer's stablecoin wallet ID using the get wallets endpoint.
2. Create quote: Generate a conversion quote from your fiat wallet to the customer's stablecoin wallet.
3. 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
• 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

1. Create a quote by sending the POST /api/v1/quote request.

   {
       "from": "ETH",
       "to": "USDC",
       "fromWalletLsid": "a:26012726855253:zMpcRHg:1",
       "useMaximum": false,
       "useMinimum": false,
       "reference": "REF6435921392",
       "toWalletLsid": "a:26012659807080:SsaiV4j:1",
       "amountIn": "0.004",
       "payInMethod": "wallet",
       "payOutMethod": "wallet"
   }

   For detailed request parameters, refer to the Create Quote endpoint documentation.

   You will receive a response with the quote price, applicable fees, and the quote UUID.

   {
     ...
     "quoteUuid": "019bfe65-92d8-7738-b855-1734474b279f",
     "price": "0.004",
     "fees": "0.0004",
     "quoteStatus": "PENDING",
     "paymentStatus": "PENDING"
     ...
   }

   note

   Many customers prefer a one-step flow rather than creating a quote and then accepting it separately. If you want to explore auto-accepting quotes via the quote endpoint, contact BVNK support or check the Create Quote endpoint documentation for available options.

2. Accept the quote by sending the PUT /api/v1/quote/{uuid} request with the quote UUID received in the previous response.

   curl -X PUT https://api.staging.bvnk.com/api/v1/quote/accept/019bfe65-92d8-7738-b855-1734474b279f

   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 stablecoins are credited to the user's wallet immediately.

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