Rihpig

Posted on Apr 23 • Originally published at apidog.com

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

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

Apidog를 지금 사용해보세요

이 가이드는 계정 생성부터 샌드박스/프로덕션 환경 설정, Bearer 토큰 인증, 결제 및 지불 엔드포인트 활용, Circle Wallets(Web3 서비스), 크로스체인 전송 프로토콜(CCTP), 개발자 제어 지갑의 엔티티 비밀 암호문, 웹훅 처리, 멱등성 관리, KYB 규정 준수까지 전체 개발자 환경을 빠르게 구현할 수 있도록 안내합니다. curl 및 Node.js 코드 스니펫이 포함되어 있으니 바로 복붙하며 따라올 수 있습니다. 참고: 최고의 법정화폐 온램프 오프램프 API 가이드에서는 Circle과 경쟁 서비스 비교도 제공합니다.

💡프로토타입 개발 시 REST와 Web3를 유연하게 다루는 API 클라이언트가 필요합니다. Apidog는 Circle의 Bearer 인증, 환경 전환, 웹훅 리플레이를 하나의 워크스페이스에서 처리할 수 있어 샌드박스/프로덕션을 쉽게 테스트할 수 있습니다.

요약 (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 발행(브릿지 리스크 없음)

더 폭넓은 Web3 인프라 비교는 최고의 암호화폐 지갑 API와 Alchemy API 사용법 분석을 참고하세요.

인증 및 설정

console.circle.com에서 계정 생성
샌드박스(무료)와 프로덕션(기업 인증 필요) 환경 제공
- 프로덕션은 KYB(Know Your Business) 승인 필요: 법인 서류, 실소유주, 자금 계좌 등 제출 필수
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 개발자 제어 지갑

엔티티 비밀(entity secret): 32바이트 16진수, 대시보드에서 등록 필요
모든 쓰기 호출에 RSA 공개키로 암호화된 entitySecretCiphertext 필요
Node SDK는 자동 처리, 직접 구현 시 요청마다 새 암호문 필요

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, 블록체인 정보를 가집니다. 테스트넷 USDC는 Circle Faucet에서 충전하세요.

개발자 제어 지갑에서 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" } },
});

응답에서 트랜잭션 id를 받고, /v1/w3s/transactions/{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 암호화 필요. 응답은 결제 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는 스마트 컨트랙트 기반이며, 온체인 소각+Circle 증명 서비스 조합으로 사용합니다.

소스 체인 TokenMessenger 컨트랙트에서 depositForBurn 호출
https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash}로 폴링, status: "complete"와 attestation 획득
대상 체인 MessageTransmitter 컨트랙트에서 메시지 바이트+증명으로 receiveMessage 호출

최종적으로 대상 체인에서 네이티브 USDC가 발행됩니다. 별도 브릿지 토큰/유동성 위험 없음.

웹훅 및 멱등성

모든 이벤트(payments, payouts, transfers, chargebacks)는 /v1/notifications/subscriptions에 등록된 HTTPS 엔드포인트로 POST
웹훅은 ECDSA 키로 서명됨. /v1/notifications/publicKey/get에서 공개키를 받아 X-Circle-Signature 헤더 검증 필수
변경 엔드포인트는 모두 Idempotency-Key 헤더 필요(UUID v4). 같은 키로 재시도 시 중복 결제 없이 기존 응답 반환

일반적인 오류 및 속도 제한

401 Unauthorized: 토큰 누락/형식 오류/환경 불일치
400 invalid_entity_secret_ciphertext: 암호문 재사용/오래된 공개키로 암호화 시 발생, 암호문 재생성 필요
429 Too Many Requests: 샌드박스는 초당 10요청, 프로덕션은 볼륨에 따라 조정. 지수 백오프 적용
insufficient_funds: 지갑 USDC 부족, 카드 AVS/CVV 실패

카드 인프라 비교는 최고의 카드 발행 API 요약 참고.

Circle API 가격

샌드박스: 무료
Circle Mint: 기관 고객의 USDC 발행/상환 수수료 없음(자격 요건 충족 시)
Circle Payments: 카드 거래당 일반적으로 2.9% + 30센트(대량 협상 가능)
미국 송금: 거래당 몇 달러 수준
W3S 지갑: 지갑/거래별 요금
프로덕션 견적은 영업팀 문의
CCTP: 자체 무료(체인 가스비 별도)

Apidog로 Circle API 테스트

Circle 인터페이스는 REST, 서명 웹훅, 온체인 컨트랙트를 모두 포함해서 단일 Postman 컬렉션으로 커버하기 어렵습니다.

Apidog은 Circle OpenAPI 사양을 직접 임포트하고, 샌드박스/프로덕션 Bearer 토큰을 별도 환경으로 저장, 카드 결제·지불·웹훅 검증을 하나의 실행 단계로 연결하는 테스트 스크립트 작성이 가능합니다.

Apidog를 다운로드하고 Circle 사양을 개발자 포털에서 로드하세요.

웹훅 처리기는 목 서버로 시뮬레이션 후 실제 엔드포인트로 전환할 수 있습니다.

팀 단위라면 공유 워크스페이스로 엔티티 비밀 노출 없이 컬렉션을 버전 관리하세요.

FAQ

Circle API를 테스트하려면 KYB가 필요한가요?

아니요. 샌드박스 계정은 누구나 이메일로 가입할 수 있습니다. 실거래(프로덕션)만 KYB 필수. 샌드박스에는 체인별 USDC Faucet도 제공합니다.

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 인증 사용. 최종 사용자는 SDK로 거래 승인, 개발자는 개인 키를 직접 다루지 않아도 됨.

개발자 제어 지갑(Developer-Controlled)은 엔티티 비밀로 백엔드 서명 권한 부여.

Circle은 솔라나 및 비EVM 체인 지원하나요?

네. W3S는 솔라나, 앱토스, 니어, 다양한 EVM L2 지원. CCTP v2(2024)로 솔라나↔EVM 네이티브 USDC 이동 가능.

엔티티 비밀 안전하게 교체하려면?

대시보드에서 새 엔티티 비밀 생성/등록. 전환 기간 동안 이전/새 암호문 병행 사용, SDK는 환경 변수 기반이므로 롤링 배포로 안전하게 교체 가능합니다.

DEV Community