Blog

Como Usar a API da Circle para Negociar USDC

Mark Ponomarev

Mark Ponomarev

23 junho 2025

Como Usar a API da Circle para Negociar USDC

O USD Coin (USDC) emergiu como um pilar de estabilidade e confiabilidade. Como uma stablecoin totalmente reservada e lastreada em dólar, o USDC preenche a lacuna entre a moeda fiduciária tradicional e o crescente mundo dos ativos digitais. Ele oferece a velocidade e o alcance global das criptomoedas, mantendo a estabilidade de preço do dólar americano, tornando-o um meio ideal para comércio, negociação e remessas na internet.

No centro do ecossistema USDC está a Circle, a principal desenvolvedora da stablecoin. A Circle oferece um conjunto de APIs que capacitam desenvolvedores e empresas a integrar o USDC em seus aplicativos de forma contínua. A Circle Mint API, em particular, oferece um poderoso portal para cunhar novos USDC, resgatá-los por moeda fiduciária e transferi-los por uma infinidade de blockchains suportadas. Isso não é "negociação" no sentido de especular sobre flutuações de preço em uma bolsa de mercado aberto, mas sim algo mais fundamental: a capacidade de mover valor programaticamente, de entrar dos trilhos financeiros tradicionais para o mundo digital e de sair novamente.

Este artigo é o seu guia completo para dominar a API da Circle para transações USDC. Embarcaremos em uma jornada detalhada, começando pela configuração inicial da sua conta de desenvolvedor até a execução de transferências e pagamentos complexos. Abordaremos:

Ao final deste guia, você terá o conhecimento e exemplos práticos necessários para construir aplicativos sofisticados que aproveitam o poder de um dólar digital estável, global e programável.

💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e tudo-em-um para sua Equipe de Desenvolvedores trabalhar em conjunto com máxima produtividade?

Apidog entrega todas as suas demandas e substitui o Postman por um preço muito mais acessível!
botão

Primeiros Passos com a Circle

Antes de escrever uma única linha de código, você precisa configurar seu ambiente de desenvolvimento e obter suas credenciais. Esta etapa fundamental é crucial para um processo de integração suave.

Ambientes Sandbox vs. Produção

A Circle oferece dois ambientes distintos para suas APIs: Sandbox e Produção. Compreender seus papéis é o primeiro passo para uma integração bem-sucedida e segura.

Os hosts de API para cada ambiente são os seguintes:

Ambiente URL do Host da API
Sandbox https://api-sandbox.circle.com
Produção https://api.circle.com

Ao longo deste guia, todos os exemplos usarão a URL do sandbox. Esta é uma prática crítica: sempre desenvolva e teste primeiro no ambiente sandbox.

Criando Sua Conta Sandbox

Sua jornada começa criando uma conta de desenvolvedor da Circle, que lhe dará acesso ao ambiente sandbox.

  1. Navegue até o Site da Circle: Vá para a página oficial de desenvolvedores da Circle.
  2. Inscreva-se: Procure a opção para se inscrever em uma conta de desenvolvedor ou sandbox. Você precisará fornecer algumas informações básicas, como seu endereço de e-mail e uma senha segura.
  3. Verifique Seu E-mail: Após enviar o formulário de inscrição, você receberá um e-mail de verificação. Clique no link dentro deste e-mail para ativar sua conta.
  4. Acesse o Painel: Uma vez que sua conta seja verificada, você pode fazer login no painel do desenvolvedor. Este painel é o seu centro para gerenciar seus aplicativos, chaves de API e visualizar sua atividade no sandbox.

Gerando Sua Primeira Chave de API

Uma chave de API é um token secreto único que autentica as requisições do seu aplicativo para a API da Circle. Ela prova que uma requisição está vindo de você e não de um terceiro não autorizado.

Veja como gerar uma chave de API a partir do seu novo painel do sandbox:

  1. Faça login na sua conta sandbox de desenvolvedor da Circle.
  2. Navegue até a Seção de Chaves de API: No painel, encontre uma seção rotulada "API Keys" (Chaves de API) ou "Developer Settings" (Configurações de Desenvolvedor).
  3. Crie uma Nova Chave: Haverá uma opção para "Create a New API Key" (Criar uma Nova Chave de API). Clique nela.
  4. Nomeie Sua Chave: Dê à sua chave um nome descritivo (por exemplo, "Meu Aplicativo de Negociação - Teste"). Isso ajuda a identificar o propósito da chave mais tarde, especialmente se você tiver várias chaves para diferentes aplicativos.
  5. Copie e Proteja Sua Chave: Após a criação, sua chave de API será exibida na tela. Esta é a única vez que a chave completa será mostrada. Você deve copiá-la imediatamente e armazená-la em um local seguro, como um gerenciador de senhas ou um arquivo de variável de ambiente para seu projeto. Não codifique sua chave de API diretamente em seu código-fonte.

Sua chave de API é uma informação sensível. Qualquer pessoa que a possua pode fazer requisições em nome de sua conta. Trate-a com o mesmo nível de segurança que você trataria uma senha.

Autenticação e Configuração Inicial

Com sua chave de API em mãos, você está pronto para fazer suas primeiras chamadas à API da Circle. O primeiro passo é dominar o processo de autenticação e testar sua conexão para garantir que tudo esteja configurado corretamente.

Autenticação de API: O Token Bearer

A API da Circle usa o esquema de autenticação Bearer Token. Este é um método padrão de autenticação HTTP onde cada requisição de API deve incluir um cabeçalho Authorization contendo sua chave de API.

O formato do cabeçalho é: Authorization: Bearer SUA_CHAVE_API

Você deve substituir SUA_CHAVE_API pela chave secreta real que você gerou no capítulo anterior.

Testando Sua Conexão

Antes de mergulhar em transações complexas, é essencial realizar dois testes simples: um para verificar a conectividade básica de rede com os servidores da API da Circle e outro para verificar se sua chave de API está configurada corretamente.

Testando Conectividade Bruta com /ping

O endpoint /ping é uma verificação de saúde simples. Não requer autenticação e é usado para confirmar que você pode alcançar os servidores da API da Circle.

Veja como chamá-lo usando cURL, uma ferramenta comum de linha de comando para fazer requisições HTTP:

curl -H 'Accept: application/json' \
  -X GET --url https://api-sandbox.circle.com/ping

Resposta de Sucesso:

Se sua conexão for bem-sucedida, a API retornará um objeto JSON simples:

{
  "message": "pong"
}

Se você receber esta resposta, estabeleceu com sucesso uma conexão com o ambiente sandbox. Caso contrário, verifique sua conexão de rede, firewalls ou quaisquer erros de digitação na URL.

Testando Sua Chave de API com /v1/configuration

Agora, vamos testar se sua chave de API é válida e está formatada corretamente. O endpoint /v1/configuration recupera informações básicas de configuração para sua conta e requer autenticação.

Aqui está o comando cURL. Lembre-se de substituir ${SUA_CHAVE_API} pela sua chave de API real. Por segurança, é melhor usar uma variável de ambiente.

# É uma boa prática armazenar sua chave de API em uma variável de ambiente
# export YOUR_API_KEY='SUA_CHAVE_AQUI'

curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/configuration

Resposta de Sucesso:

Uma requisição bem-sucedida retornará um objeto JSON contendo o ID da sua carteira principal. O masterWalletId é o identificador único para a carteira primária associada à sua conta onde seus fundos são mantidos.

{
  "data": {
    "payments": {
      "masterWalletId": "1234567890"
    }
  }
}

Resposta de Erro:

Se houver um problema com sua chave de API ou como você formatou o cabeçalho Authorization, você receberá um erro 401 Unauthorized.

{
  "code": 401,
  "message": "Autorização malformada. As credenciais estão codificadas corretamente?"
}

Se você vir este erro, verifique novamente o seguinte:

Usando SDKs da Circle para Integração Mais Simples

Embora você sempre possa interagir com a API diretamente usando requisições HTTP, a Circle fornece Kits de Desenvolvimento de Software (SDKs) para linguagens de programação populares como Node.js, Python e Java. Esses SDKs lidam com o código boilerplate para autenticação, formatação de requisições e análise de respostas, tornando seu processo de desenvolvimento mais rápido e menos propenso a erros.

Aqui está um breve exemplo de como você pode inicializar o SDK Node.js da Circle:

// Instale o SDK primeiro: npm install @circle-fin/circle-sdk

import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle(
  process.env.CIRCLE_API_KEY, // Chave de API da variável de ambiente
  CircleEnvironments.sandbox   // Apontando para o ambiente sandbox
);

async function getConfiguration() {
  try {
    const response = await circle.core.getConfiguration();
    console.log(response.data.payments.masterWalletId);
  } catch (error) {
    console.error(error.response.data);
  }
}

getConfiguration();

Usar um SDK abstrai os detalhes de baixo nível, permitindo que você se concentre na lógica de negócios do seu aplicativo. Recomendamos usar um SDK para qualquer projeto sério.

Conceitos Essenciais e Recursos da API

Para usar a API da Circle de forma eficaz, você deve entender seu modelo de dados subjacente. A API é construída em torno de um conjunto de recursos—objetos JSON que representam as entidades centrais no sistema, como pagamentos, carteiras e transferências.

Uma Visão Geral dos Recursos da API

Os recursos da Circle podem ser categorizados em vários grupos:

Recursos Primários: Estes representam as principais ações financeiras que você pode realizar.

Métodos e Instrumentos:

Recursos Aninhados: São objetos que frequentemente são incorporados em outros recursos para fornecer informações detalhadas.

Aprofundando: O Objeto Payment

Um payment é como você recebe fundos. Embora a API suporte pagamentos com cartão, para casos de uso de USDC, você frequentemente estará lidando com pagamentos que financiam sua carteira Circle.

Exemplo de Objeto Payment:

{
  "id": "e665ea6e-3a53-4f93-a85e-45178d48d9ea",
  "type": "payment",
  "merchantId": "c680d087-7b41-40aa-95a2-68febcdddb22",
  "merchantWalletId": "1000002853",
  "amount": {
    "amount": "10.00",
    "currency": "USD"
  },
  "source": {
    "id": "86461e9f-db1a-487f-915b-641138062e7c",
    "type": "card"
  },
  "description": "New customer payment",
  "status": "confirmed",
  "fees": {
    "amount": "0.58",
    "currency": "USD"
  },
  "createDate": "2024-01-10T02:29:53.888Z",
  "updateDate": "2024-01-10T02:32:19.421Z"
}

Atributos Chave:

Aprofundando: O Objeto Transfer

Uma transfer é, sem dúvida, o objeto mais importante para "negociar" ou mover USDC. Ele representa o movimento de moeda digital.

Exemplo de Objeto Transfer:

{
  "id": "c332d75a-3870-410c-b26a-93e5a3ab90e8",
  "source": {
    "type": "wallet",
    "id": "1000002853"
  },
  "destination": {
    "type": "blockchain",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "chain": "ETH"
  },
  "amount": {
    "amount": "150.50",
    "currency": "USD"
  },
  "status": "pending",
  "createDate": "2024-05-15T18:44:03.484Z",
  "updateDate": "2024-05-15T18:44:03.484Z"
}

Atributos Chave:

Objetos de Origem e Destino

Esses objetos aninhados são vitais, pois definem o fluxo de fundos em qualquer transação.

O campo type deles determina o tipo de origem ou destino:

Cadeias e Moedas Suportadas

A Circle é agnóstica em relação a cadeias e está constantemente expandindo seu suporte. No final de 2024, o USDC está disponível em várias blockchains importantes, incluindo:

Você deve especificar o identificador chain correto ao fazer transferências. Para moedas fiduciárias, a API suporta principalmente USD e EUR. A currency no objeto Money deve ser sempre definida como USD ao lidar com transferências de USDC.

Executando Transações: O Ciclo de Vida Completo

Agora chegamos ao cerne da questão: usar a API para movimentar dinheiro. Percorreremos um ciclo de vida completo: entrada de moeda fiduciária para obter USDC, transferência desse USDC para um endereço externo e, finalmente, a saída de volta para uma conta bancária fiduciária.

Passo 1: Entrada de Moeda Fiduciária com um Payment

Para muitos aplicativos, o primeiro passo é converter a moeda fiduciária de um cliente em USDC em sua carteira Circle. O endpoint da API Create Payment é usado para isso. Embora a API suporte várias fontes de pagamento, focaremos no conceito.

Vamos supor que um cliente esteja pagando a você $500. Você faria uma requisição POST para /v1/payments.

Requisição de API para Criar um Pagamento:

curl -X POST \
  https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "seu-uuid-unico-aqui-para-pagamento",
        "source": {
          "id": "algum-id-de-cartao-ou-banco",
          "type": "card"
        },
        "amount": {
          "amount": "500.00",
          "currency": "USD"
        },
        "description": "Pagamento por serviços prestados"
      }'

Nota Importante: A idempotencyKey é crucial aqui. É um ID único (no formato UUID) que você gera para esta requisição. Se você enviar a mesma requisição duas vezes (por exemplo, devido a um erro de rede), a Circle reconhecerá a chave e processará o pagamento apenas uma vez. Abordaremos isso em mais detalhes no próximo capítulo.

Uma vez que este pagamento seja processado e seu status se torne confirmed (confirmado) ou paid (pago), o valor equivalente em USDC (menos taxas) será creditado em seu merchantWalletId.

Passo 2: Verificando o Saldo da Sua Carteira

Após receber um pagamento, você vai querer verificar se os fundos chegaram. Você pode verificar o saldo de qualquer uma de suas carteiras, mas mais comumente sua carteira principal.

Requisição de API para Obter Saldos:

curl -X GET \
  https://api-sandbox.circle.com/v1/wallets/${YOUR_WALLET_ID}/balances \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Substitua ${YOUR_WALLET_ID} pelo masterWalletId que você recuperou anteriormente.

Resposta da API:

A resposta será uma lista de saldos, um para cada moeda que você possui.

{
  "data": {
    "available": [
      {
        "amount": "495.50",
        "currency": "USD"
      }
    ],
    "unsettled": [
      {
        "amount": "0.00",
        "currency": "USD"
      }
    ]
  }
}

O saldo available (disponível) é o que você pode transferir ou sacar imediatamente.

Passo 3: Transferindo USDC On-Chain

Este é o cerne do uso de USDC. Você pode transferir fundos de sua carteira para qualquer endereço externo em uma blockchain suportada. Isso é perfeito para pagar fornecedores, mover fundos para um protocolo DeFi ou enviar valor para um usuário.

Digamos que você queira enviar 100 USDC para um endereço Ethereum.

Requisição de API para Criar uma Transferência:

curl -X POST \
  https://api-sandbox.circle.com/v1/transfers \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "outro-uuid-unico-para-transferencia",
        "source": {
          "type": "wallet",
          "id": "1000002853"
        },
        "destination": {
          "type": "blockchain",
          "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
          "chain": "ETH"
        },
        "amount": {
          "amount": "100.00",
          "currency": "USD"
        }
      }'

Detalhes do Corpo da Requisição:

A API responderá com um objeto Transfer, inicialmente com um status de pending (pendente).

Entendendo as Confirmações de Blockchain

Transações on-chain não são instantâneas. Uma transferência deve ser transmitida para a rede e então confirmada por mineradores ou validadores. O status de sua transferência só mudará para complete (completo) depois que ela tiver recebido um número suficiente de confirmações na blockchain. A Circle gerencia essa complexidade para você. Você pode rastrear o status tanto consultando o endpoint GET /v1/transfers/{id} quanto, preferencialmente, usando webhooks (abordado no próximo capítulo) para receber uma notificação assim que a transferência for concluída.

Passo 4: Saída de USDC para Fiat com um Payout

A etapa final no ciclo de vida é converter seu USDC de volta para moeda fiduciária em uma conta bancária. Isso é feito por meio de um payout (saque). Antes de criar um saque, você deve primeiro vincular e verificar uma conta bancária, o que cria um objeto Wire Account.

Uma vez que você tenha uma conta bancária de destino configurada (com seu próprio id), você pode criar o saque.

Requisição de API para Criar um Saque:

curl -X POST \
  https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "outro-uuid-unico-para-saque",
        "destination": {
          "type": "wire",
          "id": "seu-uuid-de-conta-bancaria-aqui"
        },
        "amount": {
          "amount": "250.00",
          "currency": "USD"
        }
      }'

A API responderá com um objeto Payout. O status será pending (pendente) inicialmente e transitará para complete (completo) assim que os fundos tiverem sido enviados com sucesso para o banco de destino.

Recursos Avançados e Melhores Práticas

Para construir um aplicativo verdadeiramente robusto e escalável, você precisa ir além das chamadas básicas de API e aproveitar os recursos avançados que a Circle oferece. Esses recursos são projetados para garantir a integridade dos dados, fornecer atualizações em tempo real e tornar seu aplicativo resiliente.

Requisições Idempotentes: Prevenindo Gastos Duplos

Mencionamos a idempotencyKey várias vezes, mas sua importância não pode ser subestimada. Em sistemas financeiros, realizar acidentalmente uma operação duas vezes (como enviar um pagamento ou uma transferência) pode ser catastrófico. Problemas de rede podem fazer com que uma requisição expire, mesmo que o servidor a tenha processado com sucesso. Sem idempotência, seu aplicativo pode tentar novamente a requisição automaticamente, levando a uma transação duplicada.

Como funciona:

Isso garante que uma requisição específica só possa ser executada uma vez, não importa quantas vezes seja enviada.

Melhor Prática: Sempre gere e envie uma idempotencyKey para cada operação POST.

Atualizações em Tempo Real com Webhooks

Consultar uma API repetidamente para verificar o status de uma transação (GET /v1/transfers/{id}) é ineficiente e lento. A abordagem correta e moderna é usar webhooks.

Um webhook é uma mensagem automatizada enviada de um aplicativo (Circle) para outro aplicativo (o seu) quando um evento específico ocorre. Você pode configurar uma URL no seu painel da Circle onde deseja receber essas notificações.

Quando o status de um pagamento, transferência ou saque muda, a Circle enviará uma requisição POST para a sua URL configurada com um payload de notificação contendo o objeto atualizado.

Exemplo de Payload de Notificação para uma Transferência Concluída:

{
  "notification": {
    "id": "notification-uuid",
    "type": "transfers",
    "subscriptionId": "seu-id-de-assinatura"
  },
  "transfer": {
    "id": "c332d75a-3870-410c-b26a-93e5a3ab90e8",
    "source": { ... },
    "destination": { ... },
    "amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "status": "complete",
    "transactionHash": "0x123abc...",
    "createDate": "2024-05-15T18:44:03.484Z",
    "updateDate": "2024-05-15T18:48:12.123Z"
  }
}

Ao ouvir essas notificações, seu aplicativo pode reagir instantaneamente a eventos como uma transferência concluída ou um pagamento falho, proporcionando uma experiência de usuário muito melhor e permitindo a automação em tempo real.

Paginação e Filtragem: Lidando com Grandes Conjuntos de Dados

À medida que seu aplicativo cresce, você acumulará milhares de pagamentos, transferências e outros registros. Solicitar todos eles de uma vez usando um endpoint GET como /v1/transfers seria lento e complicado.

A API da Circle usa paginação baseada em cursor para resolver isso. Ao listar recursos, a resposta conterá apenas um número limitado de itens (a "página"). Você pode controlar o tamanho desta página com o parâmetro pageSize. Para obter a próxima ou a página anterior de resultados, você usa os parâmetros pageAfter ou pageBefore, passando o ID do último ou primeiro item que você viu.

Exemplo: Obtendo a primeira página de 20 transferências:
GET /v1/transfers?pageSize=20

Exemplo: Obtendo a próxima página de 20 transferências:
GET /v1/transfers?pageSize=20&pageAfter={id_da_ultima_transferencia_da_pagina_anterior}

Você também pode filtrar resultados com base em intervalos de tempo (timestamps from e to) e outros atributos específicos do recurso.

Tratamento de Erros: Construindo um Aplicativo Resiliente

As coisas podem e vão dar errado. Uma requisição de API pode falhar devido a uma entrada inválida, fundos insuficientes ou um problema temporário do servidor. Um aplicativo robusto deve antecipar e lidar com esses erros graciosamente.

A API da Circle usa códigos de status HTTP padrão para indicar o resultado de uma requisição.

Quando ocorre um erro, o corpo da resposta da API conterá um objeto JSON com mais detalhes.

Exemplo de Resposta de Erro (400 Bad Request):

{
  "code": 2,
  "message": "Parâmetro inválido ou ausente. Veja os detalhes para mais informações.",
  "errors": [
    {
      "location": "body",
      "message": "endereço de destino é inválido",
      "param": "destination.address"
    }
  ]
}

Seu código deve sempre ser envolvido em blocos try/catch (ou o equivalente para sua linguagem) para lidar com possíveis exceções de chamadas de API. Você deve registrar os detalhes do erro e, se apropriado, apresentar uma mensagem útil ao usuário.

Conclusão: Capacitando o Futuro das Finanças

Percorremos todo o processo de uso da API da Circle para transacionar com USDC. Desde a configuração inicial do sandbox e autenticação até a execução de pagamentos, transferências e saques, você agora possui o conhecimento fundamental para construir aplicativos financeiros poderosos. Também exploramos os recursos avançados como idempotência, webhooks e tratamento de erros que são essenciais para criar sistemas profissionais e prontos para produção.

A API da Circle faz mais do que apenas permitir que você movimente uma moeda digital; ela fornece os trilhos programáveis para um novo sistema financeiro nativo da internet. Ao abstrair as complexidades da tecnologia blockchain e fornecer uma API limpa e orientada a recursos, a Circle capacita os desenvolvedores a inovar e construir a próxima geração de comércio global, serviços financeiros e pagamentos ponto a ponto.

As possibilidades são vastas. As ferramentas estão em suas mãos. Agora, vá construir algo incrível.

💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e tudo-em-um para sua Equipe de Desenvolvedores trabalhar em conjunto com máxima produtividade?

Apidog entrega todas as suas demandas e substitui o Postman por um preço muito mais acessível!
botão

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar