Construtor de fluxos | Documentação Web3Card

FluxoPasse o mouse num passo para ver a chamada

Carteira na BaseA carteira do usuário

Web3Card BridgeRota entre redes

Carteira do usuárioNa BNB Chain

Contrato do programaO seu programa na BNB Chain

VISACartão VisaCartão virtual

Código

Estas chamadas mostram como queremos que a API v2 funcione neste fluxo. A API v2 está planejada: nenhum endereço foi publicado ainda, e os nomes podem mudar. $W3C_API é o endereço da API.

Pedir uma rota

A rota leva o token até o token do programa na BNB Chain, na carteira do próprio usuário. A resposta traz as transações para o usuário assinar: nada passa pela plataforma.

curl -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" }
  }'

Resposta

{
  "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
}

Acompanhar a transferência

A transferência é uma operação: acompanhe até ela terminar, ou espere o evento dela.

curl -X GET "$W3C_API/operations/op_8a1f" \
  -H "Authorization: Bearer $W3C_API_KEY"

Resposta

{
  "id": "op_8a1f",
  "type": "bridge.transfer",
  "status": "completed",
  "received": { "network": "bnb", "token": "USDT", "amount": "99.62" }
}

Depositar no programa

O depósito sai da carteira do usuário e entra no contrato do seu programa. A API devolve as duas transações para assinar: a autorização do valor exato e o depósito.

curl -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"
  }'

Resposta

{
  "depositId": "dep_2210",
  "network": "bnb",
  "transactions": [
    { "type": "approve", "to": "0x…", "data": "0x…" },
    { "type": "deposit", "to": "0x…", "data": "0x…" }
  ]
}

Recarregar o cartão

Leva saldo do programa para o cartão. A chave de idempotência deixa repetir a chamada sem risco.

curl -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"
  }'

Resposta

{
  "operationId": "op_c410",
  "status": "pending"
}

Receber o evento

Os seus sistemas recebem um evento assinado quando o fluxo termina. Confira a assinatura antes de confiar nele.

# 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"
  }
}

O que o construtor de fluxos mostra

Ilustrativo

O construtor de fluxos mostra como um token chega a um cartão do seu programa, e as chamadas que queremos que a API v2 tenha em cada passo. A API v2 está planejada: nenhum endereço foi publicado ainda, e os nomes, os campos e as respostas podem mudar. A Bridge no app dos seus usuários está sendo construída.

O construtor de fluxos roda no seu navegador. Nada é enviado e nenhuma carteira é conectada. Os valores, os endereços e os identificadores do código são exemplos.

Escolha um token e a rede dele à esquerda, depois onde ele deve terminar. O fluxo à direita desenha cada passo por que o token passa. Passe o mouse num passo para ver a chamada dele no código abaixo, ou clique para ir até ela.

Onde um fluxo começa

Um fluxo começa na carteira do próprio usuário, numa destas redes.

Rede	Tokens
BNB Chain	BNB, USDT, USDC
Ethereum	ETH, USDT, USDC
Arbitrum	ETH, USDT, USDC
Polygon	POL, USDT, USDC
Base	ETH, USDC

O token do seu projeto mostra como um token do seu próprio projeto pode entrar no mesmo fluxo: primeiro ele é trocado numa exchange descentralizada (DEX) da rede dele, depois segue a mesma rota de qualquer outro token. Isso só funciona para um token que tenha mercado numa DEX da rede dele.

Onde um fluxo termina

Destino	O que acontece
A sua carteira	O usuário recebe o token do programa, na BNB Chain, na própria carteira
Contrato do programa	O token do programa é depositado no contrato do seu programa e vira saldo do programa
Cartão Visa	Depois do depósito, o saldo vai do programa para um cartão do usuário, pronto para usar

O token do programa é o token com que o contrato do seu programa trabalha: USDT ou USDC, na BNB Chain.

Os passos de uma rota

Passo	O que faz
Troca em DEX	Converte o token no token do programa, na mesma rede
Web3Card Bridge	Traz o token de outra rede para a BNB Chain, convertendo no caminho quando precisa
Depósito	Leva o token do programa da carteira do usuário para o contrato do seu programa
Recarga	Leva saldo do programa para um cartão. A taxa de recarga é paga por cima, então o cartão recebe o valor inteiro

O usuário assina cada transação na própria carteira. Os tokens saem da carteira do usuário e chegam na mesma carteira: nada passa por você nem pela plataforma no caminho. Um token que já é o token do programa na BNB Chain pula a troca e a ponte.

As chamadas

Cada passo do fluxo tem uma chamada no painel Código, em cURL e em JavaScript, com uma resposta de exemplo. Elas seguem os princípios da API v2: operações que você acompanha até terminarem, uma chave que deixa repetir um pedido sem risco, e eventos assinados.

Chamada	O que faz
Pedir uma rota	Devolve a rota até o token do programa e as transações para o usuário assinar
Acompanhar a transferência	Lê a operação da transferência até ela terminar
Depositar no programa	Devolve as duas transações de um depósito: a autorização do valor exato e o depósito
Recarregar o cartão	Leva saldo do programa para um cartão. Leva uma chave de idempotência
Receber o evento	Os seus sistemas recebem um evento assinado quando o fluxo termina

$W3C_API é o endereço da API, que ainda não foi publicado, e $W3C_API_KEY é a sua chave.

Página	O que traz
Playground de cartões	Desenhe um cartão de exemplo e veja o que cada ação faz
Visão geral da API v2	O que é a API v2 e os princípios em que ela é desenhada
Cartões: países	Onde os cartões não funcionam, e onde podem ser usados com Apple Pay

O que o construtor de fluxos mostra​

Onde um fluxo começa​

Onde um fluxo termina​

Os passos de uma rota​

As chamadas​

Páginas relacionadas​

O que o construtor de fluxos mostra

Onde um fluxo começa

Onde um fluxo termina

Os passos de uma rota

As chamadas

Páginas relacionadas