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 kullanıma hazır 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 istiyorsanız, Circle API ile bu işlemleri hızlıca entegre edebilirsiniz. Resmi belgeleri developers.circle.com adresinde, USDC'nin temel bilgilerini ise circle.com/en/usdc adresinde bulabilirsiniz.

Apidog'u bugün deneyin

Bu rehberde, Circle API'nin geliştirici yüzeyini adım adım uygulamalı olarak ele alıyoruz: hesap oluşturma, sandbox ve üretim ortamı, Bearer token kimlik doğrulama, ödeme/para çekme uç noktaları, Circle Cüzdanları (Web3 Hizmetleri), Zincirler Arası Transfer Protokolü (CCTP), varlık gizli şifre metni, webhook'lar, idempotency ve KYB uyumluluğu. Terminalinizde hızlıca deneyebileceğiniz curl ve Node.js kod örnekleri bulacaksınız. Ayrıca, en iyi fiat on-ramp off-ramp API'si rehberimizde Circle'ın rakipleriyle karşılaştırmasını okuyabilirsiniz.

💡Prototip oluştururken hem REST hem de Web3 protokollerini destekleyen bir API istemcisine ihtiyacınız olacak. Apidog, Circle'ın Bearer kimlik doğrulamasını, ortam geçişini ve webhook doğrulamasını tek bir çalışma alanında yönetmenizi sağlar, böylece kodunuzu yeniden yazmaya gerek kalmadan sandbox ve üretim ortamlarını paralel test edebilirsiniz.

Kısaca

• Circle API; Circle Ödemeleri (kartlar, ACH, havaleler), Circle Mint (kurumsal USDC ihracı), Circle Cüzdanları / W3S (programlanabilir cüzdanlar) ve CCTP (zincirler arası USDC transferi) gibi hizmetleri kapsar.
• Kimlik doğrulama: Bearer token ile yapılır. Sandbox anahtarları TEST_API_KEY:, üretim anahtarları LIVE_API_KEY: ile başlar.
• Geliştirici Kontrollü Cüzdanlar için her yazma işlemi, RSA ile şifrelenmiş ve her istekte yeniden oluşturulan bir varlık gizli şifre metni gerektirir.
• CCTP, yerel USDC'yi sekizden fazla zincir arasında taşır.
• KYB onayı yalnızca üretim ortamı için gereklidir. Sandbox herkese açıktır.
• Idempotency anahtarları ile tekrar eden isteklerde çifte işlem riskini önleyin. Webhook imzalarını /notifications/publicKey/get ile doğrulayın.

Circle API Nedir?

Circle, USDC'yi ihraç eden ve ABD dolarına sabit tutan bir ödeme altyapısı sunar. Circle API ile aşağıdaki ürünleri uygulamanıza hızlıca entegre edebilirsiniz:

• Circle Ödeme API'si: Kart, ACH, SEPA ve havale ile ödeme alır, tutarı USDC olarak cüzdanınıza aktarır.
• Circle Para Çekme API'si: USDC bakiyenizden banka hesabına havale veya ACH ile para 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 zincirde USDC'yi yakıp hedef zincirde eşdeğerini basarak köprülenmiş token yerine doğrudan yerel varlık transferi sağlar.

Daha geniş Web3 API ekosistemiyle karşılaştırmak için en iyi kripto cüzdanı API'si ve Alchemy API nasıl kullanılır makalelerine göz atabilirsiniz.

Kimlik Doğrulama ve Kurulum

1. console.circle.com adresinden hesap oluşturun.
2. Sandbox ortamı ücretsiz ve anında erişilebilir; üretim için KYB onayı gereklidir (belge yükleme, sahip bilgileri ve fon hesabı).
3. Geliştiriciler → API Anahtarları bölümünden yeni API anahtarı oluşturun. Format:
   • Sandbox: TEST_API_KEY:abc123:xyz789
   • Üretim: LIVE_API_KEY:...
4. Bearer token ile çağrı yapın:

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 Geliştirici Kontrollü Cüzdanlar için ayrıca 32 baytlık bir hex dizesi olan bir varlık sırrı oluşturun ve konsolda kaydedin. Her yazma çağrısında, bu sırrı Circle'ın RSA genel anahtarı ile şifreleyip entitySecretCiphertext olarak iletmeniz gerekir. Node SDK bunu sizin için yönetir.

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

Temel Uç Noktalar

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

Bir cüzdan seti oluşturup içine cüzdan ekleyin:

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, id, address ve blockchain bilgisini içerir. Devam etmek için test ağı USDC 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" } },
});

İşlem ID'sini, GET /v1/w3s/transactions/{id} ile veya webhook üzerinden takip edebilirsiniz.

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": "[e-mail]", "sessionId": "..." }
  }'

Kart verilerini, /v1/encryption/public ile alınan Circle genel anahtarıyla PGP şifreleyin. Yanıtta ödeme idsi döner ve işlem durumu takip edilebilir.

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": "[e-mail]" }
  }'

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

CCTP, doğrudan API yerine zincir üzeri akıllı sözleşmeler ve Circle onay servisi ile çalışır:

1. Kaynak zincirde TokenMessenger sözleşmesi üzerinde depositForBurn çağrısı yapın.
2. https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} adresinden status: "complete" ve attestation alın.
3. Hedef zincirde MessageTransmitter sözleşmesi üzerinde receiveMessage çağrısı yapın.

Sonuç olarak, köprülenmiş token riski olmadan yerel USDC transfer etmiş olursunuz.

Webhook'lar ve Idempotency

Circle, /v1/notifications/subscriptions üzerinden abone olduğunuz HTTPS uç noktalarına olayları POST eder (payments, payouts, transfers, chargebacks). Tüm webhook'lar ECDSA ile imzalanır; /v1/notifications/publicKey/get ile genel anahtarı alıp X-Circle-Signature başlığını doğrulayın.

Her değişen istek için Idempotency-Key (UUID v4) kullanın. Aynı anahtar ile yapılan tekrar isteklerde çifte işlem yerine orijinal yanıt döner.

Yaygın Hatalar ve Oran Sınırları

• 401 Unauthorized: Bearer token eksik, yanlış veya ortam hatalı.
• 400 invalid_entity_secret_ciphertext: Şifre metni tekrar kullanıldı veya eski anahtarla şifrelendi. Her istekte yeni oluşturun.
• 429 Too Many Requests: Sandbox ortamında saniyede yaklaşık 10 istek limiti; üretim ortamında hacme bağlı değişir.
• insufficient_funds: Kaynak cüzdan veya kartta yeterli bakiye yok.

Kart altyapısı hakkında daha fazla detay için en iyi kart ihraç API'si derlememize göz atın.

Circle API Fiyatlandırması

• Sandbox ücretsizdir.
• Circle Mint: Kurumsal hacimlerde üretimde ücretsiz, işlem başına ücret yok.
• Circle Ödemeleri: Kart işleminde genellikle %2,9 + 30 cent, pazarlık edilebilir.
• Havaleler: İşlem başına birkaç dolar.
• W3S cüzdanları: Cüzdan ve işlem başına ücretlendirilir, teklif için satış ekibiyle iletişime geçin.
• CCTP: Protokol ücretsizdir, sadece zincir gas ücretlerini ödersiniz.

Apidog ile Circle API'sini Test Etme

Circle API REST uç noktaları, imzalı webhook'lar ve zincir üzeri sözleşmeleri kapsar. Tek bir Postman koleksiyonu ile tüm akışı yönetmek zordur. Apidog, Circle'ın OpenAPI spesifikasyonunu doğrudan içe aktarır, sandbox ve prod Bearer tokenlarını ayrı ortamlar olarak saklar ve zincirleme testler oluşturmanıza imkân tanır.

Apidog'u indirin ve Circle spesifikasyonunu yükleyin. Sahte sunucu ile webhook teslimatlarını simüle edin, hazır olduğunuzda gerçek uç noktaya geçin. Paylaşılan çalışma alanı ile varlık sırrınızı güvenli tutun ve koleksiyonunuzu kodunuzla birlikte versionlayın.

Sıkça Sorulan Sorular

Circle API'sini test etmek için KYB'ye ihtiyacım var mı?

Hayır, sandbox hesabı e-posta adresi olan herkese açıktır. Yalnızca üretimde gerçek fon taşımak için KYB gerekir. Sandbox'ta test ağı USDC muslukları mevcuttur.

Circle Mint ve Circle Cüzdanları arasındaki fark nedir?

Circle Mint kurumsal giriş noktasıdır: USD yatırırsınız, USDC alırsınız. Circle Cüzdanları/W3S ise son kullanıcılar için cüzdan ve işlem altyapısı sunar. Tüketici uygulamaları cüzdanları, hazine uygulamaları ise doğrudan Mint'i kullanır. MoonPay API nasıl kullanılır yazımızda perakende alternatiflere bakabilirsiniz.

CCTP köprü riskinden nasıl kaçınır?

Kaynak zincirde USDC yakılır, Circle'ın imzalı onayıyla hedef zincirde yeniden basılır. Köprüde kilitli likidite olmadığı için köprü hack'leri riski yoktur.

Circle Cüzdanlarını anahtarları tutmadan kullanabilir miyim?

Evet, W3S'deki Kullanıcı Kontrollü Cüzdanlar MPC ve PIN ile çalışır; kullanıcılar SDK ile yetkilendirir, siz özel anahtara erişmezsiniz. Geliştirici Kontrollü Cüzdanlar ise arka uçta varlık sırrı ile imza yetkisini taşır.

Circle, Solana ve EVM olmayan zincirleri destekliyor mu?

Evet. W3S, Solana, Aptos, NEAR ve çeşitli EVM L2'leri kapsar. CCTP v2 ile Solana desteği artırıldı; yerel USDC artık Solana ve EVM ekosistemi arasında özgürce taşınabiliyor.

Varlık sırrını güvenli bir şekilde nasıl döndürürüm?

Kontrol paneliyle yeni bir sır oluşturup kaydedin, geçiş sürecinde eski ve yeni şifre metinlerini paralel çalıştırın. SDK, ortam değişkeninden sırrı otomatik okur.

---

Circle API entegrasyonunuza başlamak ve işlemlerinizi kolaylaştırmak için yukarıdaki kod örneklerini ve Apidog ile test yöntemlerini doğrudan uygulayabilirsiniz.