Skip to main content

Top-ups

A card is spendable while its vault holds balance. Users top up by transferring supported tokens to their vault address; no API call is required to receive funds, though the API provides everything you need to build a great top-up UX.

API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

Get the deposit address​

The vault address is the deposit address. Show it (and a QR code) in your app:

curl https://api.web3card.dev/v1/vaults/vlt_77aa \
  -H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"
{
  "id": "vlt_77aa",
  "userId": "usr_9f4c",
  "chain": "polygon",
  "address": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
  "currency": "USDC",
  "balance": "487.35",
  "status": "active"
}
caution

Deposits must be sent on the vault's chain. Tokens sent on a different chain are not credited automatically; recovery requires manual support intervention.

Stablecoin top-ups​

Transfers of the vault's settlement currency (USDC or USDT) are credited as soon as the transfer reaches finality on the vault's chain. A vault.credited webhook is emitted with the amount and transaction hash.

Project token top-ups​

If your program has token top-ups enabled, transfers of your project token to the vault are converted to the settlement currency at market rate and credited as stablecoin balance. The conversion details are attached to the webhook event:

{
  "type": "vault.credited",
  "data": {
    "vaultId": "vlt_77aa",
    "source": "token_conversion",
    "tokenIn": "YOURTOKEN",
    "amountIn": "1500.00",
    "currency": "USDC",
    "amountCredited": "487.35",
    "rate": "0.32490",
    "txHash": "0x9c2f…e11a"
  }
}

Balance display​

Use GET /vaults/{id} for the authoritative balance. The balance field already excludes amounts held by pending authorizations, so it is safe to display as "available to spend".

Last updated on