Circle API 사용법: USDC 결제, 지갑, 지급 완벽 가이드

Circle은 시가총액 기준으로 두 번째로 큰 스테이블코인인 USDC를 발행하며, 커스터디, 규정 준수 또는 뱅킹 인프라를 처음부터 구축할 필요 없이 온체인에서 달러를 이동할 수 있는 API 스택을 제공합니다. 마켓플레이스 지불을 몇 분 안에 정산하거나, 사용자가 카드를 통해 입금하고 USDC로 인출하게 하거나, 단일 호출로 8개 블록체인에 걸쳐 스테이블코인을 이동하고 싶었다면, Circle API가 가장 빠른 방법입니다. 공식 문서는 developers.circle.com에 있으며, USDC 기본 가이드는 circle.com/en/usdc에서 키를 사용하기 전에 읽어볼 가치가 있습니다.

이 가이드는 계정 생성, 샌드박스 vs 프로덕션, Bearer 토큰 인증, 결제 및 지불 엔드포인트, Circle Wallets (Web3 서비스), 크로스체인 전송 프로토콜(CCTP), 개발자 제어 지갑(Developer-Controlled Wallets)을 위한 엔티티 비밀 암호문, 웹훅, 멱등성, KYB 규정 준수에 이르는 전체 개발자 환경을 안내합니다. 터미널에 붙여넣을 수 있는 curl 및 Node 스니펫을 기대하세요. 관련 읽을거리: 최고의 법정화폐 온램프 오프램프 API에 대한 저희 가이드는 Circle을 가장 가까운 경쟁자들과 비교합니다.

💡

프로토타입을 제작하는 동안 REST와 Web3를 유창하게 다루는 API 클라이언트도 필요할 것입니다. Apidog는 Circle의 Bearer 인증, 환경 전환 및 웹훅 리플레이를 단일 작업 공간에서 처리하므로, 컬렉션을 다시 작성할 필요 없이 샌드박스와 프로덕션을 나란히 테스트할 수 있습니다.

button

요약 (TL;DR)

Circle API는 서비스군입니다: Circle Payments (카드, ACH, 송금), Circle Mint (기관 USDC 발행), Circle Wallets / W3S (프로그래밍 가능한 지갑), CCTP (네이티브 크로스체인 USDC 소각 및 발행).
Bearer 토큰으로 인증합니다. 샌드박스 키는 TEST_API_KEY:로 시작하고, 프로덕션 키는 LIVE_API_KEY:로 시작합니다.
개발자 제어 지갑(Developer-Controlled Wallets)은 모든 쓰기 작업에 엔티티 비밀 암호문(RSA 암호화, 요청당 재생성)을 필요로 합니다.
CCTP는 이더리움, 아비트럼, 베이스, 옵티미즘, 폴리곤 PoS, 아발란체, 솔라나 등에서 증명된 소각-발행을 통해 네이티브 USDC를 이동시킵니다.
프로덕션 사용을 위해서는 KYB 승인이 필요합니다. 샌드박스는 모든 개발자에게 공개되어 있습니다.
모든 변경 요청에 멱등성 키를 사용하고, /notifications/publicKey/get에서 공개 키로 웹훅 서명을 확인하세요.

Circle API란 무엇인가요?

Circle은 USDC를 발행하고 미국 달러에 고정된 상태를 유지하는 레일을 운영하는 규제된 결제 회사입니다. Circle API는 다음 네 가지 제품 라인을 노출하며, 이들을 조합하여 사용할 수 있습니다:

Circle Payments API는 카드, ACH, SEPA, 송금을 허용하고, 그 결과를 판매자 지갑의 USDC로 정산합니다.
Circle Payouts API는 귀하의 USDC 잔액에서 온보딩된 수혜자의 은행 계좌로 송금 또는 ACH를 보냅니다.
Circle Wallets (W3S)는 여러 체인에서 커스터디 또는 개발자 제어 지갑을 생성하고, 트랜잭션에 서명하며, 가스를 처리합니다.
CCTP는 소스 체인에서 USDC를 소각하고 대상 체인에서 동등한 USDC를 발행하여, 브릿지된 래퍼가 아닌 네이티브 자산을 얻게 합니다.

Circle을 범용 Web3 인프라와 비교하고 있다면, 최고의 암호화폐 지갑 API 및 Alchemy API 사용법에 대한 저희 분석을 읽어 각 도구가 어디에 적합한지 확인해보세요.

인증 및 설정

console.circle.com에서 계정을 생성하세요. 콘솔은 샌드박스와 프로덕션 두 가지 환경을 제공합니다. 샌드박스는 무료이며 셀프 서비스입니다. 프로덕션은 KYB(Know Your Business) 승인이 필요하며, 이는 영업일 기준 며칠이 소요되며 법인 서류, 실소유주 정보 및 자금 조달 계좌가 필요합니다.

개발자 → API 키에서 API 키를 생성하세요. 키 형식은 샌드박스에서는 TEST_API_KEY:<id>:<secret>이며, 프로덕션에서는 LIVE_API_KEY:<id>:<secret>입니다. Bearer 토큰으로 전달하세요:

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

기본 URL:

샌드박스: https://api-sandbox.circle.com
프로덕션: https://api.circle.com

W3S의 개발자 제어 지갑(Developer-Controlled Wallets)의 경우 엔티티 비밀(entity secret)도 필요합니다. 이는 한 번 생성하여 대시보드를 통해 등록하는 32바이트 16진수 문자열입니다. 모든 쓰기 호출에는 Circle의 RSA 공개 키로 암호화된 새로운 entitySecretCiphertext가 포함되어야 합니다. Node SDK는 이를 자동으로 재생성합니다. 직접 구현하는 경우, Circle이 재사용된 값을 거부하므로 각 요청마다 암호문을 교체해야 합니다.

Node SDK 설치:

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

핵심 엔드포인트

지갑 세트 및 지갑 생성

W3S의 지갑은 지갑 세트(하나의 HD 시드를 공유하는 그룹) 내에 존재합니다. 먼저 세트를 생성한 다음 그 안에 지갑을 만듭니다.

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);

각 지갑은 id, address, 그리고 지갑이 존재하는 블록체인을 반환합니다. Circle Faucet에서 테스트넷 USDC로 자금을 조달하여 계속 진행하세요.

개발자 제어 지갑에서 USDC 전송

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

응답은 GET /v1/w3s/transactions/{id}를 통해 폴링하거나 웹훅을 통해 수신할 수 있는 트랜잭션 id를 반환합니다.

카드 결제를 받고 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": "..." }
  }'

카드 데이터는 Circle의 공개 키(/v1/encryption/public에서 가져올 수 있음)로 PGP 암호화되어야 합니다. 응답은 pending → confirmed → paid 상태로 이동하는 결제 id를 반환합니다.

송금 또는 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" }
  }'

CCTP를 사용하여 USDC 크로스체인 이동

CCTP는 스마트 계약 프로토콜이며 REST 엔드포인트가 아니므로, 온체인 소각과 Circle의 증명 서비스를 결합해야 합니다:

소스 체인의 TokenMessenger 계약에서 depositForBurn을 호출합니다.
status: "complete"가 되고 attestation 16진수 블롭을 받을 때까지 https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash}를 폴링합니다.
메시지 바이트와 증명과 함께 대상 체인의 MessageTransmitter 계약에서 receiveMessage를 호출합니다.

결과적으로 검증 가능한 소각에 따라 무에서 생성된 네이티브 USDC를 대상 체인에서 얻게 됩니다. 래핑된 토큰이나 브릿지 유동성 위험이 없습니다.

웹훅 및 멱등성

Circle은 /v1/notifications/subscriptions를 통해 구독하는 모든 HTTPS 엔드포인트로 이벤트(payments, payouts, transfers, chargebacks)를 POST합니다. 모든 웹훅은 ECDSA 키로 서명됩니다. /v1/notifications/publicKey/get에서 공개 키를 가져와 페이로드를 신뢰하기 전에 X-Circle-Signature 헤더를 확인하세요.

모든 변경 엔드포인트는 Idempotency-Key 헤더(UUID v4가 표준)를 필요로 합니다. 동일한 키로 요청을 재시도하면 중복 결제가 생성되는 대신 원래 응답이 반환됩니다. 이는 카드 및 송금의 경우 이중 전송을 용납하지 않으므로 중요합니다.

일반적인 오류 및 속도 제한

401 Unauthorized: Bearer 토큰이 없거나, 형식이 잘못되었거나, 환경이 틀렸습니다.
400 invalid_entity_secret_ciphertext: 암호문을 재사용했거나 오래된 공개 키로 암호화했습니다. 재생성하여 다시 시도하세요.
429 Too Many Requests: 샌드박스는 엔드포인트당 초당 약 10개의 요청으로 제한됩니다. 프로덕션 제한은 볼륨에 따라 조정됩니다. 지수적으로 백오프(재시도 간격 늘리기)하세요.
insufficient_funds: 소스 지갑에 USDC가 부족하거나, 소스 카드에서 AVS/CVV 확인이 실패했습니다.

카드 인프라에 대한 더 넓은 관점을 보려면, 최고의 카드 발행 API 요약에서 Circle 지불과 잘 어울리는 발행사를 다룹니다.

Circle API 가격

샌드박스는 무료입니다. 프로덕션에서 Circle Mint는 적격한 볼륨을 가진 승인된 기관 고객에게 USDC 발행 또는 상환에 대해 아무것도 청구하지 않습니다. Circle Payments는 카드 거래당 일정 비율과 고정 수수료를 부과합니다(일반적으로 2.9% + 30센트, 대량 거래 시 협상). 미국 송금 지불은 거래당 몇 달러가 소요됩니다. W3S 지갑은 지갑당 및 거래당 요금이 부과됩니다. 프로덕션 견적은 영업팀에 문의하세요. CCTP 자체는 무료입니다. 소스 및 대상 체인 가스 요금만 지불합니다.

Apidog로 Circle API 테스트

Circle의 인터페이스는 REST, 서명된 웹훅 및 온체인 계약에 걸쳐 있으므로 단일 Postman 컬렉션으로는 전체 흐름을 거의 캡처할 수 없습니다. Apidog는 Circle의 OpenAPI 사양을 직접 가져오고, 샌드박스와 프로덕션 Bearer 토큰을 별도의 환경으로 저장하며, 카드 결제, 지불 및 웹훅 검증을 하나의 실행으로 연결하는 테스트 스크립트를 작성할 수 있도록 합니다.

Apidog를 다운로드하고 Circle 개발자 포털에서 Circle 사양을 로드하세요. 웹훅 처리기를 구축하는 동안 목 서버를 사용하여 웹훅 전송을 시뮬레이션한 다음, 준비가 되면 실제 엔드포인트로 전환하세요. 팀의 경우, 공유 작업 공간은 엔티티 비밀이 채팅에 노출되지 않도록 하고 백엔드 코드와 함께 컬렉션을 버전 관리합니다.

FAQ

Circle API를 테스트하려면 KYB가 필요한가요?아니요. 샌드박스 계정은 이메일 주소가 있는 누구에게나 열려 있습니다. 프로덕션에서 실제 달러를 이동하려면 KYB만 필요합니다. 샌드박스는 지원되는 모든 체인의 USDC를 위한 수도꼭지를 제공합니다.

Circle Mint와 Circle Wallets의 차이점은 무엇인가요?Circle Mint는 기관 온램프입니다: USD를 전송하면 USDC를 얻습니다(그 반대도 마찬가지). Circle Wallets / W3S는 최종 사용자를 위한 커스터디 및 거래 인프라입니다. 대부분의 소비자 앱은 Wallets를 사용하고, 재무 앱은 Mint를 직접 사용합니다. Mint 수준의 발행이 필요하지 않은 경우, MoonPay API 사용법 가이드에서 소매 전용 대안을 다룹니다.

CCTP는 어떻게 브릿지 위험을 피하나요?네이티브 USDC는 소스 체인에서 소각되고 Circle의 서명된 증명에 따라 대상 체인에서 새로 발행됩니다. 브릿지 익스플로잇이 자금을 유출할 수 있는 잠긴 유동성 풀이 없습니다. 여전히 Circle의 증명 서비스를 신뢰해야 하지만, 제3자 브릿지 검증자 세트를 신뢰하는 것은 아닙니다.

키를 보유하지 않고 Circle Wallets를 사용할 수 있나요?네. W3S의 사용자 제어 지갑(User-Controlled Wallets)은 MPC 및 PIN 기반 인증을 사용하므로 최종 사용자는 Circle의 SDK를 통해 거래를 승인하며, 귀하는 개인 키를 만질 필요가 없습니다. 개발자 제어 지갑(Developer-Controlled Wallets)은 엔티티 비밀을 통해 백엔드에 서명 권한을 부여합니다.

Circle은 솔라나 및 비EVM 체인을 지원하나요?네. W3S는 솔라나, 앱토스, 니어 및 여러 EVM L2를 지원합니다. CCTP v2는 2024년에 솔라나 지원을 확장하여 이제 네이티브 USDC가 솔라나와 EVM 생태계 사이를 자유롭게 이동할 수 있습니다.

엔티티 비밀을 안전하게 교체하려면 어떻게 해야 하나요?Circle은 대시보드를 통한 엔티티 비밀 교체를 지원합니다. 새 비밀을 생성하고 등록한 다음, 짧은 전환 기간 동안 이전 및 새 암호문을 동시에 실행합니다. SDK는 환경 변수에 있는 비밀을 읽으므로 롤링 배포를 통해 깔끔하게 처리됩니다.