Circle API Kullanımı: USDC Ödemeleri, Cüzdanlar ve Ödemeler

Circle, piyasa değerine göre ikinci en büyük stabilcoin olan USDC'yi ihraç eder ve saklama, uyumluluk veya bankacılık altyapısı oluşturmadan dolarları zincir üzerinde taşımanızı sağlayan bir dizi API sunar. Bir pazar yeri ödemesini dakikalar içinde gerçekleştirmek, bir kullanıcının kartla para yatırıp USDC olarak çekmesini sağlamak veya sekiz blockchain üzerinde stabilcoinleri tek bir çağrıyla taşımak istediyseniz, Circle API buraya giden en kısa yoldur. Resmi belgeler developers.circle.com adresinde bulunur ve USDC'nin temel bilgileri circle.com/en/usdc adresinde, tuşlara dokunmadan önce okunmaya değerdir.

Bu rehber, tüm geliştirici yüzeyini adım adım açıklar: hesap oluşturma, sandbox ve üretim ortamı, Bearer token kimlik doğrulaması, ödemeler ve para çekme uç noktaları, Circle Cüzdanları (Web3 Hizmetleri), Zincirler Arası Transfer Protokolü (CCTP), Geliştirici Kontrollü Cüzdanlar için varlık gizli şifre metni, webhook'lar, idempotency ve KYB uyumluluğu. Terminalinize yapıştırabileceğiniz curl ve Node kod parçacıkları bekleyebilirsiniz. İlgili okuma: en iyi fiat on-ramp off-ramp API'si hakkındaki rehberimiz Circle'ı en yakın rakipleriyle karşılaştırır.

💡

Prototip oluştururken hem REST hem de Web3'ü akıcı bir şekilde konuşan bir API istemcisine de ihtiyacınız olacaktır. Apidog, Circle'ın Bearer kimlik doğrulamasını, ortam geçişini ve webhook tekrarını tek bir çalışma alanında yönetir, böylece koleksiyonunuzu yeniden yazmadan sandbox ve üretim ortamlarını yan yana test edebilirsiniz.

button

Kısaca

Circle API bir hizmet ailesidir: Circle Ödemeleri (kartlar, ACH, havaleler), Circle Mint (kurumsal USDC ihracı), Circle Cüzdanları / W3S (programlanabilir cüzdanlar) ve CCTP (yerel zincirler arası USDC yakma-basma).
Bearer token ile kimlik doğrulayın; sandbox anahtarları `TEST_API_KEY:` ile, üretim anahtarları ise `LIVE_API_KEY:` ile başlar.
Geliştirici Kontrollü Cüzdanlar, tüm yazma işlemleri için bir varlık gizli şifre metni (RSA ile şifrelenmiş, her istekte yeniden oluşturulan) gerektirir.
CCTP, onaylı bir yakma-basma işlemi aracılığıyla yerel USDC'yi Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana ve daha fazlası arasında taşır.
Üretim için KYB onayı gereklidir. Sandbox herhangi bir geliştiriciye açıktır.
Her değişen istekte idempotency anahtarları kullanın ve webhook imzalarını `/notifications/publicKey/get` adresinden gelen genel anahtar ile doğrulayın.

Circle API Nedir?

Circle, USDC ihraç eden ve onu ABD dolarına sabit tutan altyapıyı işleten düzenlemeye tabi bir ödeme şirketidir. Circle API, karıştırıp eşleştirebileceğiniz dört ürün hattı sunar:

Circle Ödeme API'si kartları, ACH'yi, SEPA'yı ve havaleleri kabul eder, ardından sonucu satıcı cüzdanınızda USDC olarak öder.
Circle Para Çekme API'si, USDC bakiyenizden önceden eklediğiniz herhangi bir banka hesabına havale veya ACH gönderir.
Circle Cüzdanları (W3S), birden çok zincirde saklamalı veya geliştirici kontrollü cüzdanlar oluşturur, işlemleri imzalar ve gas ücretlerini yönetir.
CCTP, kaynak zincirinde USDC'yi yakar ve hedef zincirinde eşdeğer USDC'yi basar, böylece köprülenmiş bir sarmalayıcı yerine yerel varlıklar elde edersiniz.

Circle'ı genel amaçlı Web3 altyapısıyla karşılaştırıyorsanız, her aracın nereye uyduğunu görmek için en iyi kripto cüzdanı API'si ve Alchemy API nasıl kullanılır rehberimize göz atın.

Kimlik Doğrulama ve Kurulum

console.circle.com adresinden bir hesap oluşturun. Konsol size iki ortam sunar: sandbox ve üretim. Sandbox ücretsiz ve self-servistir; üretim için ise birkaç iş günü süren ve kuruluş belgeleri, faydalı sahip bilgileri ve bir fonlama hesabı gerektiren Know Your Business (KYB) onayı gerekir.

Geliştiriciler → API Anahtarları altında bir API anahtarı oluşturun. Anahtar formatı sandbox'ta `TEST_API_KEY::` veya üretimde `LIVE_API_KEY::` şeklindedir. Bunu bir Bearer token olarak iletin:

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

Temel URL'ler:

Sandbox: `https://api-sandbox.circle.com`
Üretim: `https://api.circle.com`

W3S'deki Geliştirici Kontrollü Cüzdanlar için ayrıca bir varlık sırrına ihtiyacınız vardır: bir kez oluşturup kontrol paneli aracılığıyla kaydettiğiniz 32 baytlık bir hex dizesi. Her yazma çağrısı, varlık sırrının Circle'ın RSA genel anahtarıyla şifrelenmiş hali olan yeni bir `entitySecretCiphertext` içermelidir. Node SDK bunu otomatik olarak yeniden oluşturur; eğer kendiniz yapıyorsanız, Circle tekrar kullanılan değerleri reddettiği için her istekte şifre metnini döndürün.

Node SDK'sını yükleyin:

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

Temel Uç Noktalar

Bir Cüzdan Seti ve Cüzdan Oluşturun

W3S'deki cüzdanlar bir cüzdan seti (tek bir HD tohumunu paylaşan bir grup) içinde bulunur. Önce seti oluşturun, ardından içine cüzdanlar oluşturun.

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

Her cüzdan bir `id`, bir `address` ve bulunduğu blockchain'i döndürür. Devam etmek için Circle musluğundan test ağı USDC'si ile finanse edin.

Geliştirici Kontrollü Bir Cüzdandan USDC Transfer Etme

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

Yanıt, `GET /v1/w3s/transactions/{id}` aracılığıyla sorgulayabileceğiniz veya webhook aracılığıyla dinleyebileceğiniz bir işlem `id`si döndürür.

Kart Ödemesi Kabul Edin ve USDC Olarak Ödeyin

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": "..." }
  }'

Kart verileri, Circle'ın genel anahtarıyla PGP ile şifrelenmelidir (`/v1/encryption/public` adresinden alın). Yanıt, `beklemede → onaylandı → ödendi` durumlarından geçen bir ödeme `id`si döndürür.

Havale veya ACH ile Ödeme Gönderin

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" }
  }'

USDC'yi CCTP ile Zincirler Arası Taşıyın

CCTP, bir REST uç noktası değil, bir akıllı sözleşme protokolüdür, bu nedenle zincir üzeri bir yakma işlemini Circle'ın onay hizmetiyle birleştirirsiniz:

Kaynak zincirindeki `TokenMessenger` sözleşmesi üzerinde `depositForBurn` çağrısı yapın.
`https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash}` adresini, `status: "complete"` olana ve bir `attestation` hex blob'u alana kadar sorgulayın.
Mesaj baytları ve onayı ile hedef zincirindeki `MessageTransmitter` sözleşmesi üzerinde `receiveMessage` çağrısı yapın.

Sonuç olarak, doğrulanabilir bir yakma işlemine karşı sıfırdan basılan yerel USDC'ye sahip olursunuz. Sarmalanmış tokenlar yok, köprü likidite riski yok.

Webhook'lar ve Idempotency

Circle, `/v1/notifications/subscriptions` aracılığıyla abone olduğunuz herhangi bir HTTPS uç noktasına olayları (`payments`, `payouts`, `transfers`, `chargebacks`) POST eder. Her webhook bir ECDSA anahtarıyla imzalanmıştır; `/v1/notifications/publicKey/get` adresinden genel anahtarı alın ve yükü güvenmeden önce `X-Circle-Signature` başlığını doğrulayın.

Her değişen uç nokta bir `Idempotency-Key` başlığı gerektirir (bir UUID v4 standarttır). Aynı anahtarla bir isteği yeniden denemek, yinelenen bir ödeme oluşturmak yerine orijinal yanıtı döndürür. Bu önemlidir: kartlar ve havaleler çifte gönderimleri affetmez.

Yaygın Hatalar ve Oran Sınırlamaları

`401 Unauthorized`: Bearer token eksik, hatalı biçimlendirilmiş veya yanlış ortam.
`400 invalid_entity_secret_ciphertext`: Bir şifre metnini tekrar kullandınız veya eski bir genel anahtara karşı şifrelediniz. Yeniden oluşturun ve tekrar deneyin.
`429 Too Many Requests`: Sandbox, uç nokta başına saniyede yaklaşık 10 istekle sınırlıdır; üretim limitleri hacme göre ölçeklenir. Üstel olarak geri çekilin.
`insufficient_funds`: Kaynak cüzdanda yeterli USDC yok veya kaynak kart AVS/CVV kontrolünü geçemedi.

Kart altyapısına daha geniş bir bakış için, en iyi kart ihraç API'si derlememiz, Circle ödemeleriyle iyi eşleşen ihraççıları kapsar.

Circle API Fiyatlandırması

Sandbox ücretsizdir. Üretimde, Circle Mint, uygun hacimli onaylı kurumsal müşteriler için USDC basmak veya kullanmak için ücret almaz. Circle Ödemeleri, kart işlemi başına bir yüzde artı sabit ücret alır (genellikle %2,9 + 30 sent, ölçekte müzakere edilir). ABD havaleleri için ödemeler işlem başına birkaç dolar tutarındadır. W3S cüzdanları cüzdan başına ve işlem başına fiyatlandırılır; üretim teklifi için satış ekibiyle iletişime geçin. CCTP'nin kendisi ücretsizdir; kaynak ve hedef zincir gas ücretlerini siz ödersiniz.

Apidog ile Circle API'sini Test Etme

Circle'ın yüzeyi REST, imzalı webhook'lar ve zincir üzeri sözleşmeleri kapsar, bu nedenle tek bir Postman koleksiyonu nadiren tüm akışı yakalar. Apidog, Circle'ın OpenAPI spesifikasyonunu doğrudan içe aktarır, sandbox ve üretim Bearer tokenlarını ayrı ortamlar olarak saklar ve bir kart ödemesini, bir para çekme işlemini ve bir webhook doğrulamasını tek bir çalıştırmaya zincirleyen bir test betiği yazmanıza olanak tanır.

Apidog'u indirin ve geliştirici portalından Circle spesifikasyonunu yükleyin. Doğrulama işleyicisini oluştururken webhook teslimatlarını simüle etmek için sahte sunucuyu kullanın, ardından hazır olduğunuzda gerçek bir uç noktaya geçin. Ekipler için, paylaşılan çalışma alanı, varlık sırrınızı sohbetten uzak tutar ve koleksiyonunuzu arka uç kodunuzla birlikte sürüm oluşturur.

Sıkça Sorulan Sorular

Circle API'sini test etmek için KYB'ye ihtiyacım var mı?Hayır. Sandbox hesapları e-posta adresi olan herkese açıktır. Yalnızca üretimde gerçek dolar taşımak için KYB'ye ihtiyacınız vardır. Sandbox, desteklenen her zincirde USDC için musluklarla birlikte gelir.

Circle Mint ve Circle Cüzdanları arasındaki fark nedir?Circle Mint kurumsal bir başlangıç noktasıdır: USD yatırırsınız, USDC alırsınız (ve tersi). Circle Cüzdanları / W3S, son kullanıcılarınız için saklama ve işlem altyapısıdır. Çoğu tüketici uygulaması üstte Cüzdanları kullanır; hazine uygulamaları doğrudan Mint'i kullanır. MoonPay API nasıl kullanılır rehberimiz, Mint düzeyinde ihraç etmeye ihtiyacınız yoksa yalnızca perakende için bir alternatifi kapsar.

CCTP köprü riskinden nasıl kaçınır?Yerel USDC, kaynak zincirinde yakılır ve Circle'dan imzalı bir onaya karşı hedef zincirinde yeniden basılır. Bir köprü istismarının boşaltabileceği kilitli bir likidite havuzu yoktur. Hala Circle'ın onay hizmetine güvenirsiniz, ancak üçüncü taraf bir köprü doğrulayıcı setine güvenmezsiniz.

Circle Cüzdanlarını anahtarları tutmadan kullanabilir miyim?Evet. W3S'deki Kullanıcı Kontrollü Cüzdanlar MPC ve PIN tabanlı kimlik doğrulamasını kullanır, bu nedenle son kullanıcılar işlemleri Circle'ın SDK'sı aracılığıyla yetkilendirir ve siz asla özel bir anahtara dokunmazsınız. Geliştirici Kontrollü Cüzdanlar, imza yetkisini varlık sırrı aracılığıyla arka ucunuza verir.

Circle, Solana ve EVM olmayan zincirleri destekliyor mu?Evet. W3S, Solana, Aptos, NEAR ve birkaç EVM L2'yi kapsar. CCTP v2, 2024'te Solana desteğini genişletti, bu nedenle yerel USDC artık Solana ile EVM ekosistemi arasında serbestçe hareket ediyor.

Varlık sırrını güvenli bir şekilde nasıl döndürürüm?Circle, kontrol paneli aracılığıyla varlık sırrı döndürmeyi destekler. Yeni bir sır oluşturun, kaydedin ve kısa bir geçiş penceresi için hem eski hem de yeni şifre metinlerini paralel olarak çalıştırın. SDK, ortam değişkeninizdeki sırrı okur, bu nedenle kayan bir dağıtım bunu sorunsuz bir şekilde halleder.