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

A Circle emite USDC, a segunda maior stablecoin por capitalização de mercado, e expõe um conjunto de APIs que permitem movimentar dólares on-chain sem construir infraestrutura de custódia, conformidade ou bancária do zero. Se você já quis liquidar um pagamento de marketplace em minutos, permitir que um usuário deposite via cartão e saque como USDC, ou movimentar stablecoins em oito blockchains com uma única chamada, a API da Circle é o caminho mais curto. A documentação oficial está em developers.circle.com, e o guia básico de USDC em circle.com/en/usdc vale a pena ler antes de começar a codificar.

Este guia aborda toda a superfície de desenvolvimento: criação de conta, sandbox vs. produção, autenticação com token Bearer, endpoints de pagamentos e saques, Circle Wallets (Serviços Web3), o Cross-Chain Transfer Protocol (CCTP), ciphertext de segredo da entidade para Wallets Controladas por Desenvolvedores, webhooks, idempotência e conformidade KYB. Espere snippets de curl e Node que você pode colar no seu terminal. Leitura relacionada: nosso guia sobre a melhor API de fiat on-ramp e off-ramp compara a Circle com seus concorrentes mais próximos.

💡

Você também vai querer um cliente API que se comunique fluentemente em REST e Web3 enquanto você prototipa. O Apidog lida com a autenticação Bearer da Circle, alternância de ambientes e replay de webhook em um único workspace, para que você possa testar sandbox e produção lado a lado sem reescrever sua coleção.

botão

TL;DR

A API da Circle é uma família de serviços: Circle Payments (cartões, ACH, transferências bancárias), Circle Mint (emissão institucional de USDC), Circle Wallets / W3S (carteiras programáveis) e CCTP (burn-and-mint nativo de USDC entre cadeias).
Autentique-se com um token Bearer; as chaves de sandbox começam com TEST_API_KEY: e as chaves de produção com LIVE_API_KEY:.
As carteiras controladas pelo desenvolvedor (Developer-Controlled Wallets) exigem um ciphertext de segredo da entidade (criptografado em RSA, regenerado por solicitação) para todas as operações de escrita.
O CCTP move USDC nativo através de Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana e mais, via um burn-mint atestado.
A aprovação KYB é necessária para produção. O sandbox está aberto a qualquer desenvolvedor.
Use chaves de idempotência em cada solicitação de mutação e verifique as assinaturas de webhook com a chave pública de /notifications/publicKey/get.

O que é a API da Circle?

A Circle é uma empresa de pagamentos regulamentada que emite USDC e opera os trilhos que o mantêm atrelado ao dólar americano. A API da Circle expõe quatro linhas de produtos que você pode combinar:

A Circle Payments API aceita cartões, ACH, SEPA e transferências bancárias, e então liquida o resultado como USDC em sua carteira de comerciante.
A Circle Payouts API envia transferências bancárias ou ACH do seu saldo USDC para qualquer conta bancária que você tenha cadastrado como beneficiário.
A Circle Wallets (W3S) cria carteiras custodiadas ou controladas pelo desenvolvedor em múltiplas cadeias, assina transações e gerencia o gás.
O CCTP queima USDC em uma cadeia de origem e cunha USDC equivalente em uma cadeia de destino, para que você obtenha ativos nativos, e não um wrapper em ponte.

Se você estiver comparando a Circle com infraestrutura Web3 de propósito geral, leia nossa análise da melhor API de carteira de criptomoedas e o guia como usar a API da Alchemy para ver onde cada ferramenta se encaixa.

Autenticação e configuração

Crie uma conta em console.circle.com. O console oferece dois ambientes: sandbox e produção. O sandbox é gratuito e de autoatendimento; a produção exige aprovação de Know Your Business (KYB), que leva alguns dias úteis e necessita de documentos de incorporação, informações do proprietário beneficiário e uma conta de financiamento.

Gere uma chave de API em Desenvolvedores → Chaves de API. O formato da chave é TEST_API_KEY:<id>:<secret> no sandbox ou LIVE_API_KEY:<id>:<secret> em produção. Passe-a como um token Bearer:

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

URLs base:

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

Para Wallets Controladas por Desenvolvedores (Developer-Controlled Wallets) no W3S, você também precisa de um segredo de entidade: uma string hexadecimal de 32 bytes que você gera uma vez e registra via painel. Cada chamada de escrita deve incluir um entitySecretCiphertext novo, que é o segredo da entidade criptografado com a chave pública RSA da Circle. O SDK do Node o regenera automaticamente; se você fizer o seu próprio, rotacione o ciphertext a cada solicitação porque a Circle rejeita valores reutilizados.

Instale o SDK do Node:

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 retorna um id, um address e a blockchain em que reside. Financie-a com USDC da testnet da faucet da Circle para continuar.

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 retorna um id de transação que você pode consultar via GET /v1/w3s/transactions/{id} ou ouvir via 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": "buyer@example.com", "sessionId": "..." }
  }'

Os dados do cartão devem ser criptografados com PGP usando a chave pública da Circle (obtida de /v1/encryption/public). A resposta retorna um id de pagamento que transita por 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": "vendor@example.com" }
  }'

Mover USDC entre cadeias com CCTP

O CCTP é um protocolo de contrato inteligente, não um endpoint REST, então você combina uma queima on-chain com o serviço de atestação da Circle:

Chame depositForBurn no contrato TokenMessenger na cadeia de origem.
Consulte https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} até que status: "complete" e você receba um blob hexadecimal de attestation.
Chame receiveMessage no contrato MessageTransmitter na cadeia de destino com os bytes da mensagem e a atestação.

Você termina com USDC nativo na cadeia de destino, cunhado do nada contra uma queima verificável. Sem tokens empacotados, sem risco de liquidez de ponte.

Webhooks e idempotência

A Circle POSTa eventos (payments, payouts, transfers, chargebacks) para qualquer endpoint HTTPS que você assine via /v1/notifications/subscriptions. Cada webhook é assinado com uma chave ECDSA; obtenha a chave pública de /v1/notifications/publicKey/get e verifique o cabeçalho X-Circle-Signature antes de confiar no payload.

Todo endpoint de mutação requer um cabeçalho Idempotency-Key (um UUID v4 é padrão). Tentar novamente uma solicitação com a mesma chave retorna a resposta original em vez de criar um pagamento duplicado. Isso é importante: cartões e transferências bancárias não perdoam envios duplicados.

Erros comuns e limites de taxa

401 Unauthorized: Token Bearer ausente, malformado ou ambiente incorreto.
400 invalid_entity_secret_ciphertext: você reutilizou um ciphertext ou criptografou contra uma chave pública desatualizada. Regenerar e tentar novamente.
429 Too Many Requests: o sandbox é limitado a cerca de 10 requisições por segundo por endpoint; os limites de produção escalam com o volume. Recue exponencialmente.
insufficient_funds: a carteira de origem não possui USDC suficiente, ou o cartão de origem falhou na verificação AVS/CVV.

Para uma visão mais ampla da infraestrutura de cartões, nosso resumo das melhores APIs de emissão de cartões aborda emissores que combinam bem com os pagamentos da Circle.

Preços da API da Circle

O sandbox é gratuito. Em produção, a Circle Mint não cobra nada para cunhar ou resgatar USDC para clientes institucionais aprovados com volume qualificado. A Circle Payments cobra uma porcentagem mais uma taxa fixa por transação de cartão (tipicamente 2,9% + 30 centavos, negociado em escala). Pagamentos para transferências bancárias nos EUA custam alguns dólares por transação. As carteiras W3S são precificadas por carteira e por transação; entre em contato com as vendas para uma cotação de produção. O CCTP em si é gratuito; você paga o gás da cadeia de origem e destino.

Testando a API da Circle com Apidog

A superfície da Circle abrange REST, webhooks assinados e contratos on-chain, então uma única coleção do Postman raramente captura o fluxo completo. O Apidog importa a especificação OpenAPI da Circle diretamente, armazena tokens Bearer de sandbox e produção como ambientes separados e permite que você escreva um script de teste que encadeia um pagamento com cartão, um saque e uma verificação de webhook em uma única execução.

Baixe o Apidog e carregue a especificação da Circle do portal do desenvolvedor. Use o servidor de mock para simular entregas de webhook enquanto você constrói o manipulador de verificação, e então troque para um endpoint real quando estiver pronto. Para equipes, o workspace compartilhado mantém seu segredo de entidade fora do chat e versiona sua coleção junto com seu código de backend.

FAQ

Preciso de KYB para testar a API da Circle?Não. Contas sandbox estão abertas a qualquer pessoa com um endereço de e-mail. Você só precisa de KYB para movimentar dólares reais em produção. O sandbox vem com faucets para USDC em todas as cadeias suportadas.

Qual a diferença entre Circle Mint e Circle Wallets?Circle Mint é o on-ramp institucional: você transfere USD, recebe USDC (e vice-versa). Circle Wallets / W3S é a infraestrutura de custódia e transação para seus usuários finais. A maioria dos aplicativos de consumidor usa Wallets; aplicativos de tesouraria usam Mint diretamente. Nosso guia como usar a API da MoonPay cobre uma alternativa apenas para varejo, se você não precisar de emissão em nível de Mint.

Como o CCTP evita o risco de ponte?USDC nativo é queimado na cadeia de origem e recém-cunhado na cadeia de destino contra uma atestação assinada da Circle. Não há um pool de liquidez bloqueado que um exploit de ponte possa drenar. Você ainda confia no serviço de atestação da Circle, mas não está confiando em um conjunto de validadores de ponte de terceiros.

Posso usar as Circle Wallets sem possuir as chaves?Sim. As User-Controlled Wallets (Carteiras Controladas pelo Usuário) no W3S usam MPC e autenticação baseada em PIN, então os usuários finais autorizam transações via SDK da Circle e você nunca toca em uma chave privada. As Developer-Controlled Wallets (Carteiras Controladas pelo Desenvolvedor) colocam a autoridade de assinatura no seu backend via segredo da entidade.

A Circle suporta Solana e cadeias não-EVM?Sim. O W3S cobre Solana, Aptos, NEAR e várias L2s EVM. O CCTP v2 expandiu o suporte a Solana em 2024, então o USDC nativo agora se move livremente entre Solana e o ecossistema EVM.

Como faço para rotacionar o segredo da entidade com segurança?A Circle suporta a rotação do segredo da entidade via painel. Gere um novo segredo, registre-o e execute os ciphertexts antigo e novo em paralelo por uma curta janela de transição. O SDK lê o segredo que estiver na sua variável de ambiente, então um deploy rolling o gerencia de forma limpa.