Base walletThe user's wallet
User's walletOn BNB Chain
Program contractYour program on BNB ChainThese calls show how we want API v2 to work for this flow. API v2 is planned: no endpoint is published yet, and names may change. $W3C_API stands for the API address.
- 1Get a route
The route brings the token to the program token on BNB Chain, in the user's own wallet. The response has the transactions for the user to sign: nothing goes through the platform.
Responsecurl -X POST "$W3C_API/bridge/quotes" \-H "Authorization: Bearer $W3C_API_KEY" \-H "Content-Type: application/json" \-d '{"userId": "usr_9f4c","wallet": "0x71C2…3a4F","from": { "network": "base", "token": "USDC", "amount": "100.00" },"to": { "network": "bnb", "token": "USDT" }}'{"quoteId": "qt_51de","route": ["swap", "bridge"],"receive": { "network": "bnb", "token": "USDT", "minimum": "99.40" },"transactions": [{ "chainId": 8453, "to": "0x…", "data": "0x…" }],"operationId": "op_8a1f","expiresIn": 30} - 2Follow the transfer
The transfer is an operation: follow it until it ends, or wait for its event.
Responsecurl -X GET "$W3C_API/operations/op_8a1f" \-H "Authorization: Bearer $W3C_API_KEY"{"id": "op_8a1f","type": "bridge.transfer","status": "completed","received": { "network": "bnb", "token": "USDT", "amount": "99.62" }} - 3Deposit into the program
Deposits go from the user's wallet into your program contract. The API returns the two transactions to sign: the authorization of the exact amount and the deposit.
Responsecurl -X POST "$W3C_API/funding-accounts/fa_7c21/deposits" \-H "Authorization: Bearer $W3C_API_KEY" \-H "Content-Type: application/json" \-d '{"wallet": "0x71C2…3a4F","token": "USDT","amount": "100.00"}'{"depositId": "dep_2210","network": "bnb","transactions": [{ "type": "approve", "to": "0x…", "data": "0x…" },{ "type": "deposit", "to": "0x…", "data": "0x…" }]} - 4Top up the card
Moves balance from the program to the card. The idempotency key makes a repeated call safe.
Responsecurl -X POST "$W3C_API/cards/card_3b7c/top-up" \-H "Authorization: Bearer $W3C_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: topup-usr_9f4c-0001" \-d '{"fundingAccountId": "fa_7c21","amount": "100.00"}'{"operationId": "op_c410","status": "pending"} - 5Receive the event
Your systems get a signed event when the flow ends. Check the signature before trusting it.
# POST to your webhook URL# X-W3C-Timestamp: 1792850400# X-W3C-Signature: <HMAC SHA-256 of the timestamp and the raw body>{"id": "evt_88d1","type": "operation.updated","occurredAt": "2026-10-24T14:00:00Z","data": {"operationId": "op_c410","kind": "card.top_up","status": "completed","cardId": "card_3b7c","amount": "100.00"}}
What the flow builder shows
The flow builder shows how a token reaches a card of your program, and the calls we want API v2 to have for each step. API v2 is planned: no endpoint is published yet, and the names, fields and responses may change. The Bridge in your users' app is being built.
The flow builder runs in your browser. Nothing is sent anywhere and no wallet is connected. The amounts, addresses and identifiers in the code are samples.
Pick a token and its network on the left, then where it should end. The flow on the right draws each step the token goes through. Hover a step to see its call in the code below, or click it to jump there.
Where a flow starts
A flow starts in the user's own wallet, on one of these networks.
| Network | Tokens |
|---|---|
| BNB Chain | BNB, USDT, USDC |
| Ethereum | ETH, USDT, USDC |
| Arbitrum | ETH, USDT, USDC |
| Polygon | POL, USDT, USDC |
| Base | ETH, USDC |
Your project token shows how a token of your own project can enter the same flow: it is first swapped on a decentralized exchange (DEX) of its network, then follows the same route as any other token. This only works for a token that has a market on a DEX of its network.
Where a flow ends
| Destination | What happens |
|---|---|
| Your wallet | The user receives the program token, on BNB Chain, in their own wallet |
| Program contract | The program token is deposited into your program contract and becomes program balance |
| Visa card | After the deposit, the balance is moved from the program to a card of the user, ready to spend |
The program token is the token your program contract works with: USDT or USDC, on BNB Chain.
The steps of a route
| Step | What it does |
|---|---|
| DEX swap | Converts the token into the program token, on the same network |
| Web3Card Bridge | Brings the token from another network to BNB Chain, converting it on the way when needed |
| Deposit | Moves the program token from the user's wallet into your program contract |
| Top up | Moves balance from the program to a card. The top-up fee is paid on top, so the card receives the full amount |
The user signs each transaction in their own wallet. The tokens leave the user's wallet and arrive in the same wallet: nothing goes through you or the platform on the way. A token that is already the program token on BNB Chain skips the swap and the bridge.
The calls
Each step of the flow has a call in the Code panel, in cURL and in JavaScript, with a sample response. They follow the design principles of API v2: operations you follow until they finish, a key that makes a repeated request safe, and signed events.
| Call | What it does |
|---|---|
| Get a route | Returns the route to the program token and the transactions for the user to sign |
| Follow the transfer | Reads the operation of the transfer until it ends |
| Deposit into the program | Returns the two transactions of a deposit: the authorization of the exact amount and the deposit |
| Top up the card | Moves balance from the program to a card. It carries an idempotency key |
| Receive the event | Your systems get a signed event when the flow ends |
$W3C_API stands for the address of the API, which is not published yet, and $W3C_API_KEY for your key.
Related pages
| Page | What it covers |
|---|---|
| Card playground | Design a sample card and see what each card action does |
| API v2 overview | What API v2 is and the principles it is designed on |
| Cards: countries | Where cards don't work, and where they can be used with Apple Pay |