USD 코인(USDC)은 안정성과 신뢰성의 초석으로 부상했습니다. 완전 준비금, 달러 기반 스테이블코인인 USDC는 전통적인 법정화폐와 급성장하는 디지털 자산 세계 사이의 간극을 메웁니다. 이는 미국 달러의 가격 안정성을 유지하면서 암호화폐의 속도와 글로벌 도달 범위를 제공하여 인터넷 상에서 상거래, 거래 및 송금을 위한 이상적인 매체가 됩니다.
USDC 생태계의 핵심에는 스테이블코인의 주요 개발사인 Circle이 있습니다. Circle은 개발자와 기업이 USDC를 애플리케이션에 원활하게 통합할 수 있도록 지원하는 API 스위트를 제공합니다. 특히 Circle Mint API는 새로운 USDC를 발행하고, 이를 법정화폐로 상환하며, 다양한 지원 블록체인에 걸쳐 전송할 수 있는 강력한 게이트웨이를 제공합니다. 이는 공개 시장 거래소에서 가격 변동을 투기하는 의미의 "거래"가 아니라, 그보다 더 근본적인 것입니다. 즉, 가치를 프로그래밍 방식으로 이동하고, 전통적인 금융 레일에서 디지털 세계로 온램프하며, 다시 오프램프할 수 있는 능력입니다.
이 문서는 USDC 거래를 위한 Circle API를 마스터하기 위한 포괄적인 가이드입니다. 개발자 계정의 초기 설정부터 복잡한 전송 및 결제 실행에 이르기까지 자세한 여정을 시작할 것입니다. 다룰 내용은 다음과 같습니다.
- 시작하기: 계정 설정 및 샌드박스와 프로덕션 환경의 중요한 차이점 이해하기.
- 인증: 자격 증명을 사용하여 Circle API에 안전하게 연결하기.
- 핵심 개념: 결제, 지급, 전송과 같이 API의 빌딩 블록을 형성하는 필수 데이터 모델 및 리소스에 대한 심층 분석.
- 거래 실행: 법정화폐 온램프, USDC 지갑 관리, 블록체인 간 USDC 전송, 법정화폐로 다시 오프램프하는 단계별 지침.
- 고급 기능 및 모범 사례: 오류 방지를 위한 멱등성 요청, 실시간 알림을 위한 웹훅 사용, 페이지네이션을 통한 대규모 데이터셋 처리, 견고한 오류 처리 구현과 같은 강력한 기능 활용.
이 가이드가 끝날 때쯤에는 안정적이고, 글로벌하며, 프로그래밍 가능한 디지털 달러의 힘을 활용하는 정교한 애플리케이션을 구축하는 데 필요한 지식과 실용적인 예제를 갖게 될 것입니다.
개발팀이 최고의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하시나요?
Apidog는 모든 요구 사항을 충족하며, 훨씬 저렴한 가격으로 Postman을 대체합니다!
Circle 시작하기
단 한 줄의 코드를 작성하기 전에 개발 환경을 설정하고 자격 증명을 확보해야 합니다. 이 기본 단계는 원활한 통합 프로세스에 매우 중요합니다.
샌드박스 vs. 프로덕션 환경
Circle은 API를 위한 두 가지 개별 환경을 제공합니다: 샌드박스와 프로덕션. 이들의 역할을 이해하는 것이 성공적이고 안전한 통합을 위한 첫 단계입니다.
- 샌드박스 환경: 이곳은 개인 개발을 위한 놀이터입니다. 샌드박스는 실제 금융적 결과 없이 테스트, 프로토타이핑 및 통합을 위해 설계되었습니다. 프로덕션 API의 기능을 반영하여 완전한 확신을 가지고 애플리케이션을 구축하고 개선할 수 있도록 합니다. 샌드박스에서의 거래는 테스트 네트워크를 사용하며 실제 돈이나 USDC를 포함하지 않습니다. 샌드박스 내의 모든 데이터는 프로덕션 환경과 분리되어 있습니다.
- 프로덕션 환경: 이곳은 실제 금융 거래가 발생하는 라이브 환경입니다. 샌드박스에서 코드를 철저히 테스트하고 완벽하게 만든 후에는 API 호스트를 교체하고 라이브 API 키를 사용하여 프로덕션으로 전환할 수 있습니다.
각 환경의 API 호스트는 다음과 같습니다:
환경 | API 호스트 URL |
---|---|
샌드박스 | https://api-sandbox.circle.com |
프로덕션 | https://api.circle.com |
이 가이드 전체에서 모든 예제는 샌드박스 URL을 사용할 것입니다. 이것은 중요한 모범 사례입니다: 항상 샌드박스 환경에서 먼저 개발하고 테스트하십시오.
샌드박스 계정 생성
Circle 개발자 계정을 생성하여 샌드박스 환경에 접근하는 것으로 여정이 시작됩니다.
- Circle 웹사이트로 이동: 공식 Circle 개발자 페이지로 이동합니다.
- 회원 가입: 개발자 또는 샌드박스 계정 가입 옵션을 찾습니다. 이메일 주소 및 보안 비밀번호와 같은 기본 정보를 제공해야 합니다.
- 이메일 확인: 가입 양식을 제출한 후 확인 이메일을 받게 됩니다. 이 이메일 내의 링크를 클릭하여 계정을 활성화합니다.
- 대시보드 접속: 계정이 확인되면 개발자 대시보드에 로그인할 수 있습니다. 이 대시보드는 애플리케이션, API 키를 관리하고 샌드박스 활동을 볼 수 있는 중앙 허브입니다.
첫 번째 API 키 생성
API 키는 애플리케이션의 Circle API 요청을 인증하는 고유한 비밀 토큰입니다. 이는 요청이 승인되지 않은 제3자가 아닌 귀하로부터 오는 것임을 증명합니다.
새 샌드박스 대시보드에서 API 키를 생성하는 방법은 다음과 같습니다:
- Circle 개발자 샌드박스 계정에 로그인합니다.
- API 키 섹션으로 이동: 대시보드에서 "API 키" 또는 "개발자 설정"이라는 섹션을 찾습니다.
- 새 키 생성: "새 API 키 생성" 옵션이 있을 것입니다. 클릭합니다.
- 키 이름 지정: 키에 설명적인 이름을 지정합니다 (예: "내 거래 앱 - 테스트"). 이렇게 하면 나중에 키의 목적을 식별하는 데 도움이 됩니다. 특히 여러 애플리케이션에 대해 여러 키를 가지고 있는 경우에 유용합니다.
- 키 복사 및 보안: 생성 후 API 키가 화면에 표시됩니다. 전체 키가 표시되는 것은 이때가 유일합니다. 즉시 복사하여 비밀번호 관리자 또는 프로젝트의 환경 변수 파일과 같은 안전한 위치에 저장해야 합니다. 소스 코드에 API 키를 직접 하드코딩하지 마십시오.
API 키는 민감한 정보입니다. 이를 소유한 사람은 누구나 귀하의 계정을 대신하여 요청을 할 수 있습니다. 비밀번호와 동일한 수준의 보안으로 취급하십시오.
인증 및 초기 설정
API 키를 확보했으니 이제 Circle API에 첫 번째 호출을 할 준비가 되었습니다. 첫 번째 단계는 인증 프로세스를 마스터하고 모든 것이 올바르게 구성되었는지 확인하기 위해 연결을 테스트하는 것입니다.
API 인증: 베어러 토큰
Circle API는 베어러 토큰 인증 방식을 사용합니다. 이는 모든 API 요청에 API 키를 포함하는 Authorization
헤더가 포함되어야 하는 표준 HTTP 인증 방법입니다.
헤더 형식은 다음과 같습니다: Authorization: Bearer YOUR_API_KEY
YOUR_API_KEY
를 이전 장에서 생성한 실제 비밀 키로 교체해야 합니다.
연결 테스트
복잡한 거래에 뛰어들기 전에 두 가지 간단한 테스트를 수행하는 것이 중요합니다. 하나는 Circle API 서버에 대한 기본 네트워크 연결을 확인하는 것이고, 다른 하나는 API 키가 올바르게 구성되었는지 확인하는 것입니다.
/ping
을 사용한 원시 연결 테스트
/ping
엔드포인트는 간단한 상태 확인입니다. 인증이 필요 없으며 Circle API 서버에 도달할 수 있는지 확인하는 데 사용됩니다.
HTTP 요청을 만드는 데 사용되는 일반적인 명령줄 도구인 cURL을 사용하여 호출하는 방법은 다음과 같습니다:
curl -H 'Accept: application/json' \
-X GET --url https://api-sandbox.circle.com/ping
성공적인 응답:
연결이 성공하면 API는 간단한 JSON 객체를 반환합니다:
{
"message": "pong"
}
이 응답을 받으면 샌드박스 환경에 성공적으로 연결된 것입니다. 그렇지 않은 경우 네트워크 연결, 방화벽 또는 URL의 오타를 확인하십시오.
/v1/configuration
을 사용한 API 키 테스트
이제 API 키가 유효하고 올바르게 형식화되었는지 테스트해 보겠습니다. /v1/configuration
엔드포인트는 계정에 대한 기본 구성 정보를 검색하며 인증이 필요합니다.
다음은 cURL 명령입니다. ${YOUR_API_KEY}
를 실제 API 키로 교체해야 합니다. 보안을 위해 환경 변수를 사용하는 것이 가장 좋습니다.
# API 키를 환경 변수에 저장하는 것이 가장 좋은 방법입니다.
# export YOUR_API_KEY='YOUR_KEY_HERE'
curl -H 'Accept: application/json' \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-X GET --url https://api-sandbox.circle.com/v1/configuration
성공적인 응답:
성공적인 요청은 마스터 지갑 ID를 포함하는 JSON 객체를 반환합니다. masterWalletId
는 자금이 보관되는 계정과 연결된 기본 지갑의 고유 식별자입니다.
{
"data": {
"payments": {
"masterWalletId": "1234567890"
}
}
}
오류 응답:
API 키 또는 Authorization
헤더 형식에 문제가 있는 경우 401 Unauthorized
오류를 받게 됩니다.
{
"code": 401,
"message": "Malformed authorization. Are the credentials properly encoded?"
}
이 오류가 발생하면 다음을 다시 확인하십시오:
- 키 앞에
Bearer
라는 단어와 공백을 포함했습니까? - 추가 문자나 공백 없이 전체 API 키를 올바르게 복사했습니까?
- 대시보드에서 유효하고 활성 상태인 API 키를 사용하고 있습니까?
간단한 통합을 위한 Circle SDK 사용
HTTP 요청을 사용하여 API와 직접 상호 작용할 수도 있지만, Circle은 Node.js, Python, Java와 같은 인기 있는 프로그래밍 언어용 SDK(Software Development Kits)를 제공합니다. 이 SDK는 인증, 요청 형식 지정 및 응답 구문 분석을 위한 상용구 코드를 처리하여 개발 프로세스를 더 빠르고 오류 발생 가능성을 줄여줍니다.
다음은 Circle Node.js SDK를 초기화하는 방법에 대한 간략한 예입니다:
// Install the SDK first: npm install @circle-fin/circle-sdk
import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";
const circle = new Circle(
process.env.CIRCLE_API_KEY, // API key from environment variable
CircleEnvironments.sandbox // Pointing to the sandbox environment
);
async function getConfiguration() {
try {
const response = await circle.core.getConfiguration();
console.log(response.data.payments.masterWalletId);
} catch (error) {
console.error(error.response.data);
}
}
getConfiguration();
SDK를 사용하면 낮은 수준의 세부 사항이 추상화되어 애플리케이션의 비즈니스 로직에 집중할 수 있습니다. 진지한 프로젝트의 경우 SDK를 사용하는 것을 권장합니다.
핵심 개념 및 API 리소스
Circle API를 효과적으로 사용하려면 기본 데이터 모델을 이해해야 합니다. API는 결제, 지갑, 전송과 같은 시스템의 핵심 엔티티를 나타내는 JSON 객체인 리소스 집합을 중심으로 구축됩니다.
API 리소스 개요
Circle의 리소스는 여러 그룹으로 분류할 수 있습니다:
기본 리소스: 수행할 수 있는 주요 금융 작업을 나타냅니다.
Payment Object
: 고객으로부터의 결제를 나타내며, Circle 생태계에 자금을 온램프하는 주요 방법으로 사용됩니다.Payout Object
: 외부 당사자(예: 은행 계좌)에 대한 지급을 나타내며, 자금을 오프램프하는 주요 방법으로 사용됩니다.Transfer Object
: 자신의 Circle 지갑 간 또는 외부 블록체인 주소로의 자금 이동을 나타냅니다.
메서드 및 도구:
Wallet Object
: Circle이 관리하는 자금(잔액) 저장소를 나타냅니다. 마스터 지갑을 가지고 있으며 다른 지갑을 생성할 수 있습니다.Wire Account Object
: 지급을 받기 위해 연결된 은행 계좌를 나타냅니다.
중첩된 리소스: 자세한 정보를 제공하기 위해 다른 리소스 내에 종종 포함되는 객체입니다.
Money Object
: 금액과 통화를 나타내는 표준 객체 (예:{ "amount": "100.00", "currency": "USD" }
).Source
및Destination Objects
: 거래의 자금이 어디에서 오고 어디로 가는지 지정합니다.Blockchain Address Object
: 지원되는 블록체인의 특정 주소를 나타냅니다.
심층 분석: Payment
객체
payment
는 자금을 받는 방법입니다. API는 카드 결제를 지원하지만, USDC 사용 사례의 경우 Circle 지갑에 자금을 지원하는 결제를 처리하는 경우가 많습니다.
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"
}
주요 속성:
id
(문자열): 이 결제의 고유 식별자.amount
(Money Object): 결제 금액 및 통화.source
(Source Object): 자금이 어디에서 왔는지에 대한 세부 정보 (예: 카드 또는 전신 송금).status
(문자열): 결제의 현재 상태.pending
,confirmed
,paid
또는failed
일 수 있습니다. 이는 모니터링해야 할 중요한 필드입니다.fees
(Money Object): 결제 처리에 대해 Circle이 청구하는 수수료.
심층 분석: Transfer
객체
transfer
는 USDC를 "거래"하거나 이동하는 데 있어 가장 중요한 객체라고 할 수 있습니다. 이는 디지털 통화의 이동을 나타냅니다.
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"
}
주요 속성:
id
(문자열): 이 전송의 고유 식별자.source
(Source Object): 자금이 어디에서 오는지. 외부로의 전송의 경우 거의 항상wallet
이 될 것입니다.destination
(Destination Object): 자금이 어디로 가는지. 다른 Circlewallet
이거나, 더 일반적으로 외부blockchain
주소일 수 있습니다.amount
(Money Object): 전송할 USDC 금액.status
(문자열): 전송 상태. 처음에는pending
으로 시작하여complete
또는failed
로 전환됩니다.
Source 및 Destination 객체
이러한 중첩된 객체는 모든 거래에서 자금 흐름을 정의하므로 매우 중요합니다.
이들의 type
필드는 소스 또는 대상의 종류를 결정합니다:
wallet
:id
로 식별되는 Circle 지갑.blockchain
:address
및chain
(예:ETH
,SOL
,MATIC
)으로 지정된 블록체인의 외부 주소.wire
: 지급에 사용되는 은행 계좌.card
: 결제에 사용되는 신용/직불 카드.
지원되는 체인 및 통화
Circle은 체인에 구애받지 않으며 지속적으로 지원을 확장하고 있습니다. 2024년 말 현재 USDC는 다음을 포함한 수많은 주요 블록체인에서 사용할 수 있습니다:
- 이더리움 (ETH)
- 솔라나 (SOL)
- 폴리곤 PoS (MATIC)
- 트론 (TRX)
- 아발란체 (AVAX)
- 스텔라 (XLM)
- 알고랜드 (ALGO)
- 플로우 (FLOW)
전송을 할 때 올바른 chain
식별자를 지정해야 합니다. 법정화폐의 경우 API는 주로 USD
와 EUR
를 지원합니다. Money
객체의 currency
는 USDC 전송을 처리할 때 항상 USD
로 설정해야 합니다.
거래 실행: 전체 라이프사이클
이제 핵심으로 들어가겠습니다. API를 사용하여 돈을 이동하는 방법입니다. 전체 라이프사이클을 살펴보겠습니다: 법정화폐를 온램프하여 USDC를 얻고, 해당 USDC를 외부 주소로 전송한 다음, 마지막으로 법정화폐 은행 계좌로 다시 오프램프합니다.
단계 1: Payment
를 통한 법정화폐 온램프
많은 애플리케이션에서 첫 번째 단계는 고객으로부터의 법정화폐를 Circle 지갑의 USDC로 변환하는 것입니다. Create Payment
API 엔드포인트가 이를 위해 사용됩니다. API는 다양한 결제 소스를 지원하지만, 여기서는 개념에 중점을 둘 것입니다.
고객이 $500를 결제한다고 가정해 봅시다. /v1/payments
에 POST
요청을 합니다.
결제 생성을 위한 API 요청:
curl -X POST \
https://api-sandbox.circle.com/v1/payments \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": "your-unique-uuid-here-for-payment",
"source": {
"id": "some-card-or-bank-id",
"type": "card"
},
"amount": {
"amount": "500.00",
"currency": "USD"
},
"description": "Payment for services rendered"
}'
중요 참고: idempotencyKey
는 여기서 매우 중요합니다. 이 요청을 위해 생성하는 고유한 버전 4 UUID(Universally Unique Identifier)입니다. 동일한 요청을 두 번 보내는 경우(예: 네트워크 오류로 인해) Circle은 키를 인식하고 결제를 한 번만 처리합니다. 이에 대해서는 다음 장에서 더 자세히 다룰 것입니다.
이 결제가 처리되고 status
가 confirmed
또는 paid
가 되면, 해당 USDC 금액(수수료 제외)이 merchantWalletId
에 적립됩니다.
단계 2: 지갑 잔액 확인
결제를 받은 후에는 자금이 도착했는지 확인하고 싶을 것입니다. 지갑 중 아무 지갑의 잔액을 확인할 수 있지만, 가장 일반적으로는 마스터 지갑의 잔액을 확인합니다.
잔액 조회를 위한 API 요청:
curl -X GET \
https://api-sandbox.circle.com/v1/wallets/${YOUR_WALLET_ID}/balances \
-H "Authorization: Bearer ${YOUR_API_KEY}"
${YOUR_WALLET_ID}
를 이전에 검색한 masterWalletId
로 교체하십시오.
API 응답:
응답은 보유하고 있는 각 통화에 대한 잔액 목록이 될 것입니다.
{
"data": {
"available": [
{
"amount": "495.50",
"currency": "USD"
}
],
"unsettled": [
{
"amount": "0.00",
"currency": "USD"
}
]
}
}
available
잔액은 즉시 전송하거나 지급할 수 있는 금액입니다.
단계 3: 온체인 USDC 전송
이것이 USDC 사용의 핵심입니다. 지갑에서 지원되는 블록체인의 모든 외부 주소로 자금을 전송할 수 있습니다. 이는 공급업체에게 지불하거나, DeFi 프로토콜로 자금을 이동하거나, 사용자에게 가치를 보내는 데 완벽합니다.
이더리움 주소로 100 USDC를 보내고 싶다고 가정해 봅시다.
전송 생성을 위한 API 요청:
curl -X POST \
https://api-sandbox.circle.com/v1/transfers \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": "another-unique-uuid-for-transfer",
"source": {
"type": "wallet",
"id": "1000002853"
},
"destination": {
"type": "blockchain",
"address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
"chain": "ETH"
},
"amount": {
"amount": "100.00",
"currency": "USD"
}
}'
요청 본문 분석:
idempotencyKey
: 이 특정 전송 작업에 대한 새롭고 고유한 UUID.source
:id
로 지정된 Circle 지갑.destination
: 외부 블록체인 주소.type
은blockchain
.address
는 수신자의 지갑 주소.chain
은 블록체인 식별자 (이더리움의 경우ETH
).amount
: 보낼 USDC 금액.
API는 Transfer
객체를 반환하며, 초기 status
는 pending
입니다.
블록체인 확인 이해
온체인 거래는 즉시 이루어지지 않습니다. 전송은 네트워크에 브로드캐스트된 다음 채굴자 또는 검증자에 의해 확인되어야 합니다. 전송의 status
는 블록체인에서 충분한 수의 확인을 받은 후에만 complete
로 변경됩니다. Circle은 이 복잡성을 대신 관리합니다. GET /v1/transfers/{id}
엔드포인트를 폴링하거나, 더 좋은 방법으로 웹훅(다음 장에서 다룰 내용)을 사용하여 전송이 완료되면 알림을 받을 수 있습니다.
단계 4: Payout
을 통한 USDC의 법정화폐 오프램프
라이프사이클의 마지막 단계는 USDC를 은행 계좌의 법정화폐로 다시 변환하는 것입니다. 이는 payout
을 통해 이루어집니다. 지급을 생성하기 전에 먼저 은행 계좌를 연결하고 확인해야 하며, 이는 Wire Account
객체를 생성합니다.
대상 은행 계좌가 설정되면(고유한 id
를 가짐) 지급을 생성할 수 있습니다.
지급 생성을 위한 API 요청:
curl -X POST \
https://api-sandbox.circle.com/v1/payouts \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": "yet-another-unique-uuid-for-payout",
"destination": {
"type": "wire",
"id": "your-bank-account-uuid-here"
},
"amount": {
"amount": "250.00",
"currency": "USD"
}
}'
API는 Payout
객체를 반환합니다. status
는 처음에는 pending
이며, 자금이 대상 은행으로 성공적으로 전송되면 complete
로 전환됩니다.
고급 기능 및 모범 사례
진정으로 견고하고 확장 가능한 애플리케이션을 구축하려면 기본적인 API 호출을 넘어 Circle이 제공하는 고급 기능을 활용해야 합니다. 이러한 기능은 데이터 무결성을 보장하고, 실시간 업데이트를 제공하며, 애플리케이션을 탄력적으로 만들도록 설계되었습니다.
멱등성 요청: 이중 지불 방지
idempotencyKey
는 여러 번 언급했지만, 그 중요성은 아무리 강조해도 지나치지 않습니다. 금융 시스템에서 실수로 작업을 두 번 수행하는 것(예: 결제 또는 전송을 두 번 보내는 것)은 치명적일 수 있습니다. 네트워크 문제로 인해 요청이 서버에서 성공적으로 처리되었더라도 타임아웃될 수 있습니다. 멱등성이 없으면 애플리케이션이 자동으로 요청을 재시도하여 중복 거래로 이어질 수 있습니다.
작동 방식:
- 리소스를 생성하는 모든
POST
요청(결제, 전송, 지급)에 대해 고유한 버전 4 UUID(Universally Unique Identifier)를 생성하고 요청 본문의idempotencyKey
필드에 포함해야 합니다. - Circle 서버가 요청을 받으면 이 키를 이전에 본 적이 있는지 확인합니다.
- 키가 새로운 경우 요청을 처리하고 키와 결과를 저장합니다.
- 키가 이전에 본 적이 있는 경우 요청을 다시 처리하지 않습니다. 대신 원래 요청의 결과를 단순히 반환합니다.
이는 특정 요청이 몇 번 전송되든 상관없이 한 번만 실행되도록 보장합니다.
모범 사례: 모든 POST
작업에 대해 항상 idempotencyKey
를 생성하고 전송하십시오.
웹훅을 통한 실시간 업데이트
거래 상태를 확인하기 위해 API를 반복적으로 폴링하는 것(GET /v1/transfers/{id}
)은 비효율적이고 느립니다. 올바른 최신 접근 방식은 웹훅을 사용하는 것입니다.
웹훅은 특정 이벤트가 발생할 때 애플리케이션(Circle)에서 다른 애플리케이션(귀하의 애플리케이션)으로 전송되는 자동 메시지입니다. Circle 대시보드에서 이러한 알림을 받을 URL을 구성할 수 있습니다.
결제, 전송 또는 지급의 상태가 변경되면 Circle은 구성된 URL로 업데이트된 객체를 포함하는 알림 페이로드를 사용하여 POST
요청을 보냅니다.
완료된 전송에 대한 알림 페이로드 예시:
{
"notification": {
"id": "notification-uuid",
"type": "transfers",
"subscriptionId": "your-subscription-id"
},
"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"
}
}
이러한 알림을 수신함으로써 애플리케이션은 완료된 전송 또는 실패한 결제와 같은 이벤트에 즉시 반응하여 훨씬 더 나은 사용자 경험을 제공하고 실시간 자동화를 가능하게 합니다.
페이지네이션 및 필터링: 대규모 데이터셋 처리
애플리케이션이 성장함에 따라 수천 개의 결제, 전송 및 기타 기록이 축적될 것입니다. /v1/transfers
와 같은 GET
엔드포인트를 사용하여 한 번에 모든 것을 요청하는 것은 느리고 다루기 힘들 것입니다.
Circle API는 이를 해결하기 위해 커서 기반 페이지네이션을 사용합니다. 리소스를 나열할 때 응답에는 제한된 수의 항목("페이지")만 포함됩니다. pageSize
매개변수로 이 페이지의 크기를 제어할 수 있습니다. 다음 또는 이전 결과 페이지를 얻으려면 pageAfter
또는 pageBefore
매개변수를 사용하여 이전에 본 마지막 또는 첫 번째 항목의 ID를 전달합니다.
예시: 20개 전송의 첫 번째 페이지 가져오기:GET /v1/transfers?pageSize=20
예시: 20개 전송의 다음 페이지 가져오기:GET /v1/transfers?pageSize=20&pageAfter={id_of_last_transfer_from_previous_page}
시간 범위(from
및 to
타임스탬프) 및 기타 리소스별 속성을 기반으로 결과를 필터링할 수도 있습니다.
오류 처리: 탄력적인 애플리케이션 구축
문제는 발생할 수 있고 발생할 것입니다. API 요청이 잘못된 입력, 자금 부족 또는 임시 서버 문제로 인해 실패할 수 있습니다. 견고한 애플리케이션은 이러한 오류를 예상하고 우아하게 처리해야 합니다.
Circle API는 요청의 결과를 나타내기 위해 표준 HTTP 상태 코드를 사용합니다.
2xx
(예:200 OK
,201 Created
): 성공.4xx
(예:400 Bad Request
,401 Unauthorized
,404 Not Found
): 클라이언트 측 오류. 잘못된 것을 보냈습니다.5xx
(예:500 Internal Server Error
): 서버 측 오류. Circle 측에서 문제가 발생했습니다.
오류가 발생하면 API 응답 본문에 자세한 정보가 포함된 JSON 객체가 포함됩니다.
오류 응답 예시 (400 Bad Request
):
{
"code": 2,
"message": "Invalid or missing parameter. See details for more information.",
"errors": [
{
"location": "body",
"message": "destination address is invalid",
"param": "destination.address"
}
]
}
코드에는 항상 try/catch 블록(또는 해당 언어의 동등한 기능)이 포함되어야 하며, 잠재적인 API 호출 예외를 처리해야 합니다. 오류 세부 정보를 기록하고, 적절하다면 사용자에게 유용한 메시지를 표시해야 합니다.
결론: 금융의 미래를 강화하다
우리는 Circle API를 사용하여 USDC로 거래하는 전체 과정을 살펴보았습니다. 초기 샌드박스 설정 및 인증부터 결제, 전송, 지급 실행에 이르기까지 강력한 금융 애플리케이션을 구축하기 위한 기본적인 지식을 갖추게 되었습니다. 또한 전문적이고 프로덕션에 즉시 사용 가능한 시스템을 만드는 데 필수적인 멱등성, 웹훅, 오류 처리와 같은 고급 기능도 살펴보았습니다.
Circle API는 단순히 디지털 통화를 이동하는 것 이상을 제공합니다. 이는 새로운 인터넷 기반 금융 시스템을 위한 프로그래밍 가능한 레일을 제공합니다. 블록체인 기술의 복잡성을 추상화하고 깔끔하며 리소스 지향적인 API를 제공함으로써 Circle은 개발자들이 차세대 글로벌 상거래, 금융 서비스 및 P2P 결제를 혁신하고 구축할 수 있도록 지원합니다.
가능성은 무궁무진합니다. 도구는 당신의 손에 있습니다. 이제 놀라운 것을 만들어 보세요.
개발팀이 최고의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하시나요?
Apidog는 모든 요구 사항을 충족하며, 훨씬 저렴한 가격으로 Postman을 대체합니다!