Como Usar a API Circle: Pagamentos USDC, Carteiras Digitais e Payouts

A Circle oferece USDC, a segunda maior stablecoin por capitalização de mercado, e disponibiliza APIs robustas para movimentar dólares on-chain sem necessidade de criar infraestrutura própria de custódia, compliance ou banking. Precisa liquidar pagamentos de marketplace rapidamente, aceitar depósitos via cartão e sacar em USDC, ou transferir stablecoins entre oito blockchains com uma chamada? A API da Circle é o caminho mais prático. Consulte a documentação oficial em developers.circle.com e o guia de USDC em circle.com/en/usdc antes de iniciar a implementação.

Experimente o Apidog hoje

Este guia é direto ao ponto: criação de conta, ambientes sandbox/produção, autenticação Bearer, endpoints para pagamentos e saques, Circle Wallets (Web3 Services), Cross-Chain Transfer Protocol (CCTP), ciphertext de segredo da entidade, webhooks, idempotência e exigências de KYB. Inclui exemplos prontos em curl e Node.js para uso imediato. Leitura complementar: nosso comparativo sobre API de fiat on-ramp e off-ramp.

💡
Recomendo um client API eficiente para REST e Web3 no seu protótipo. O Apidog gerencia autenticação Bearer, alternância de ambiente e replay de webhook em um único workspace – teste sandbox e produção lado a lado sem reescrever coleções.

TL;DR

• A API da Circle cobre: Circle Payments (cartões, ACH, transferências bancárias), Circle Mint (emissão/saque institucional de USDC), Circle Wallets/W3S (carteiras programáveis) e CCTP (burn-and-mint nativo entre cadeias).
• Autenticação via token Bearer. Sandbox: TEST_API_KEY:; Produção: LIVE_API_KEY:.
• Developer-Controlled Wallets exigem ciphertext do segredo da entidade (RSA, rotacionado a cada escrita).
• CCTP move USDC nativo entre Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana e outros.
• KYB obrigatório para produção; sandbox aberto para qualquer dev.
• Use chave de idempotência em cada mutação e valide assinaturas de webhook com chave pública de /notifications/publicKey/get.

O que é a API da Circle?

A Circle é uma empresa de pagamentos regulamentada, responsável pelo USDC e pela infraestrutura de liquidação atrelada ao dólar. A API da Circle oferece quatro produtos integráveis:

• Circle Payments API: aceita cartões, ACH, SEPA e transferências bancárias; liquida como USDC na sua carteira.
• Circle Payouts API: envia transferências bancárias/ACH do saldo USDC para contas bancárias cadastradas.
• Circle Wallets (W3S): cria e gerencia carteiras (custódia ou controladas pelo dev) em múltiplas blockchains, inclusive assinatura e gerenciamento de gás.
• CCTP: queima USDC em uma cadeia e emite equivalente em outra, garantindo ativos nativos (sem wrapped tokens).

Compare com soluções Web3 amplas lendo nossa análise da melhor API de wallet e o guia como usar a API da Alchemy.

Autenticação e configuração

1. Crie sua conta em console.circle.com.
2. O console tem sandbox (gratuito, autoatendimento) e produção (exige aprovação KYB com documentação e conta de funding).
3. Gere uma chave em Desenvolvedores → Chaves de API:
   • Sandbox: TEST_API_KEY:<id>:<secret>
   • Produção: LIVE_API_KEY:<id>:<secret>
4. Use como Bearer:

curl https://api-sandbox.circle.com/v1/ping \
  -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"

Base URLs:

• Sandbox: https://api-sandbox.circle.com
• Produção: https://api.circle.com

Para Developer-Controlled Wallets, crie um segredo de entidade (hexadecimal, 32 bytes) via painel. Cada operação de escrita exige um novo entitySecretCiphertext (segredo criptografado com a chave pública RSA da Circle). O SDK do Node lida com isso automaticamente. Rotacione o ciphertext a cada requisição.

Instale o SDK:

npm install @circle-fin/developer-controlled-wallets

Endpoints principais

Criar um conjunto de carteiras e uma carteira

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
});

const walletSet = await client.createWalletSet({ name: "payout-set-prod" });

const wallets = await client.createWallets({
  walletSetId: walletSet.data.walletSet.id,
  blockchains: ["ETH-SEPOLIA", "MATIC-AMOY"],
  count: 2,
});

console.log(wallets.data.wallets);

Cada carteira gerada possui id, address e blockchain. Para testar, financie com USDC de testnet via faucet da Circle.

Transferir USDC de uma carteira controlada por desenvolvedor

const transfer = await client.createTransaction({
  walletId: wallets.data.wallets[0].id,
  tokenId: "5797fbd6-3795-519d-84ca-ec4c5f80c3b1", // USDC on ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

A resposta traz o id da transação – consulte via GET /v1/w3s/transactions/{id} ou escute o webhook.

Aceitar um pagamento com cartão e liquidar como USDC

curl -X POST https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": { "id": "card_4f1c...", "type": "card" },
    "amount": { "amount": "50.00", "currency": "USD" },
    "verification": "cvv",
    "description": "Order 1093",
    "encryptedData": "<PGP-encrypted card data>",
    "metadata": { "email": "[e-mail]", "sessionId": "..." }
  }'

Os dados do cartão devem ser criptografados com PGP usando a chave pública da Circle (/v1/encryption/public). O retorno inclui id do pagamento (status: pendente → confirmado → pago).

Enviar um pagamento via transferência bancária ou ACH

curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destination": { "type": "wire", "id": "beneficiary_abc" },
    "amount": { "amount": "500.00", "currency": "USD" },
    "metadata": { "beneficiaryEmail": "[e-mail]" }
  }'

Mover USDC entre cadeias com CCTP

O CCTP é um protocolo on-chain:

1. Execute depositForBurn no contrato TokenMessenger na cadeia de origem.
2. Consulte https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} até status: "complete" e obtenha o attestation.
3. Chame receiveMessage no contrato MessageTransmitter da cadeia destino, passando os bytes da mensagem e atestação.

Assim, USDC nativo é emitido na cadeia de destino, sem wrapped tokens nem pools de liquidez.

Webhooks e idempotência

• Circle POSTa eventos (payments, payouts, transfers, chargebacks) para endpoints HTTPS cadastrados via /v1/notifications/subscriptions.
• Cada webhook é assinado (ECDSA). Obtenha a chave pública em /v1/notifications/publicKey/get e valide o header X-Circle-Signature.
• Toda mutação exige header Idempotency-Key (UUID v4 recomendado). Repetir uma requisição com a mesma chave retorna a resposta original – essencial para evitar duplicidade em pagamentos.

Erros comuns e limites de taxa

• 401 Unauthorized: token Bearer ausente, malformado ou ambiente errado.
• 400 invalid_entity_secret_ciphertext: ciphertext reutilizado ou criptografia com chave pública antiga. Gere novamente.
• 429 Too Many Requests: sandbox ≈10 req/s por endpoint; produção escala conforme volume. Implemente backoff exponencial.
• insufficient_funds: saldo insuficiente ou cartão reprovado no AVS/CVV.

Para conhecer a fundo APIs de cartões, leia nosso resumo das melhores APIs de emissão de cartões.

Preços da API da Circle

• Sandbox: gratuito.
• Produção: Circle Mint isenta para clientes institucionais qualificados. Circle Payments cobra % + taxa fixa por cartão (geralmente 2,9% + US$0,30, negociável em escala). Payouts via transferência bancária custam alguns dólares. W3S: preço por carteira e transação (contato comercial). CCTP: gratuito, exceto taxas de gás.

Testando a API da Circle com Apidog

A API da Circle envolve REST, webhooks e contratos on-chain – difícil cobrir tudo só com Postman. O Apidog importa o OpenAPI da Circle, armazena tokens por ambiente e permite scripts de teste que encadeiam pagamentos, saques e verificações de webhook em uma execução só.

Baixe o Apidog e carregue a spec da Circle. Use o mock server para simular webhooks durante o desenvolvimento, depois migre para seu endpoint real. Para equipes, o workspace compartilhado isola o segredo de entidade e versiona sua coleção junto com o backend.

FAQ

Preciso de KYB para testar a API da Circle?
Não. Sandbox aberto para qualquer e-mail. KYB só é exigido para operar em produção com dólares reais. O sandbox oferece faucets de USDC em todas as chains suportadas.

Qual a diferença entre Circle Mint e Circle Wallets?
Mint é o on-ramp institucional (USD ↔ USDC). Wallets/W3S é a infraestrutura de custódia/transação para usuários finais. Apps consumidores usam Wallets; tesourarias usam Mint. Veja o guia como usar a API da MoonPay para alternativas focadas em varejo.

Como o CCTP evita riscos de ponte?
USDC é queimado na origem e cunhado na destino, mediante atestação assinada da Circle – sem pools bloqueados, sem validadores externos. O risco de ponte é eliminado, restando apenas a confiança no atestador oficial da Circle.

Posso usar Circle Wallets sem custodiar as chaves?
Sim. User-Controlled Wallets usam MPC e autenticação por PIN, onde o usuário autoriza via SDK Circle e você nunca vê a chave privada. Developer-Controlled Wallets delegam a assinatura ao backend via segredo da entidade.

A Circle suporta Solana e cadeias não-EVM?
Sim. W3S cobre Solana, Aptos, NEAR e várias L2s EVM. O CCTP v2 incluiu suporte nativo a Solana em 2024.

Como rotacionar o segredo da entidade com segurança?
Rotacione via painel Circle, gere novo segredo, registre e rode os ciphertexts antigo e novo em paralelo durante a transição. O SDK lê do ambiente, então um deploy rolling já resolve.