# CoinCircuit > CoinCircuit is crypto payment infrastructure for African and global businesses. Accept crypto payments, move stablecoins with business wallets, create static deposit addresses, onramp and offramp stablecoins, and send global payouts. Build agentic workflows and accept payments from AI agents using our MCP server and infrastructure. This file contains every page of https://coincircuit.io as markdown, in one document. Each page is also available on its own at the .md path listed under it. The OpenAPI spec is at https://coincircuit.io/openapi.json and the API catalog at https://coincircuit.io/.well-known/api-catalog. ## Contents - [Crypto Payment Infrastructure for Africa | CoinCircuit](https://coincircuit.io/) (markdown: https://coincircuit.io/index.md) - [Agentic Payment Infrastructure | CoinCircuit AI](https://coincircuit.io/ai/) (markdown: https://coincircuit.io/ai.md) - [x402 Protocol for AI Agents | CoinCircuit](https://coincircuit.io/products/x402/) (markdown: https://coincircuit.io/products/x402.md) - [Developer Docs | CoinCircuit](https://coincircuit.io/docs/) (markdown: https://coincircuit.io/docs.md) - [Integration Guides | CoinCircuit](https://coincircuit.io/docs/guides/) (markdown: https://coincircuit.io/docs/guides.md) - [Authentication | CoinCircuit Docs](https://coincircuit.io/docs/guides/authentication/) (markdown: https://coincircuit.io/docs/guides/authentication.md) - [Payments | CoinCircuit Docs](https://coincircuit.io/docs/guides/checkout-sessions/) (markdown: https://coincircuit.io/docs/guides/checkout-sessions.md) - [Crypto Payouts | CoinCircuit Docs](https://coincircuit.io/docs/guides/crypto-payouts/) (markdown: https://coincircuit.io/docs/guides/crypto-payouts.md) - [Customer Deposit Accounts | CoinCircuit Docs](https://coincircuit.io/docs/guides/customer-deposit-accounts/) (markdown: https://coincircuit.io/docs/guides/customer-deposit-accounts.md) - [Deposit Accounts | CoinCircuit Docs](https://coincircuit.io/docs/guides/deposit-accounts/) (markdown: https://coincircuit.io/docs/guides/deposit-accounts.md) - [Donation / Tip Page | CoinCircuit Docs](https://coincircuit.io/docs/guides/donation-page/) (markdown: https://coincircuit.io/docs/guides/donation-page.md) - [Dynamic Settlement | CoinCircuit Docs](https://coincircuit.io/docs/guides/dynamic-settlement/) (markdown: https://coincircuit.io/docs/guides/dynamic-settlement.md) - [E-Commerce Crypto Checkout | CoinCircuit Docs](https://coincircuit.io/docs/guides/ecommerce-checkout/) (markdown: https://coincircuit.io/docs/guides/ecommerce-checkout.md) - [E-Commerce Plugins | CoinCircuit Docs](https://coincircuit.io/docs/guides/ecommerce-plugins/) (markdown: https://coincircuit.io/docs/guides/ecommerce-plugins.md) - [Fees | CoinCircuit Docs](https://coincircuit.io/docs/guides/fees/) (markdown: https://coincircuit.io/docs/guides/fees.md) - [Introduction | CoinCircuit Docs](https://coincircuit.io/docs/guides/introduction/) (markdown: https://coincircuit.io/docs/guides/introduction.md) - [Invoices | CoinCircuit Docs](https://coincircuit.io/docs/guides/invoices/) (markdown: https://coincircuit.io/docs/guides/invoices.md) - [Limits | CoinCircuit Docs](https://coincircuit.io/docs/guides/limits/) (markdown: https://coincircuit.io/docs/guides/limits.md) - [Marketplace Vendor Payouts | CoinCircuit Docs](https://coincircuit.io/docs/guides/marketplace-settlement/) (markdown: https://coincircuit.io/docs/guides/marketplace-settlement.md) - [MCP Integration | CoinCircuit Docs](https://coincircuit.io/docs/guides/mcp/) (markdown: https://coincircuit.io/docs/guides/mcp.md) - [Migrate from Cryptomus | CoinCircuit Docs](https://coincircuit.io/docs/guides/migrate-from-cryptomus/) (markdown: https://coincircuit.io/docs/guides/migrate-from-cryptomus.md) - [Migrate from NOWPayments | CoinCircuit Docs](https://coincircuit.io/docs/guides/migrate-from-nowpayments/) (markdown: https://coincircuit.io/docs/guides/migrate-from-nowpayments.md) - [Migrate from Triple-A | CoinCircuit Docs](https://coincircuit.io/docs/guides/migrate-from-triplea/) (markdown: https://coincircuit.io/docs/guides/migrate-from-triplea.md) - [Payment Pages | CoinCircuit Docs](https://coincircuit.io/docs/guides/payment-pages/) (markdown: https://coincircuit.io/docs/guides/payment-pages.md) - [Payout Quotes | CoinCircuit Docs](https://coincircuit.io/docs/guides/payout-quotes/) (markdown: https://coincircuit.io/docs/guides/payout-quotes.md) - [Payouts | CoinCircuit Docs](https://coincircuit.io/docs/guides/payouts/) (markdown: https://coincircuit.io/docs/guides/payouts.md) - [POS Terminals | CoinCircuit Docs](https://coincircuit.io/docs/guides/pos-terminals/) (markdown: https://coincircuit.io/docs/guides/pos-terminals.md) - [Refund & Dispute Handling | CoinCircuit Docs](https://coincircuit.io/docs/guides/refund-management/) (markdown: https://coincircuit.io/docs/guides/refund-management.md) - [Refunds | CoinCircuit Docs](https://coincircuit.io/docs/guides/refunds/) (markdown: https://coincircuit.io/docs/guides/refunds.md) - [SaaS Invoice Billing | CoinCircuit Docs](https://coincircuit.io/docs/guides/saas-invoicing/) (markdown: https://coincircuit.io/docs/guides/saas-invoicing.md) - [Sandbox Environment | CoinCircuit Docs](https://coincircuit.io/docs/guides/sandbox/) (markdown: https://coincircuit.io/docs/guides/sandbox.md) - [Stablecoin On/Off-Ramp | CoinCircuit Docs](https://coincircuit.io/docs/guides/stablecoin-onramp-offramp/) (markdown: https://coincircuit.io/docs/guides/stablecoin-onramp-offramp.md) - [Swaps | CoinCircuit Docs](https://coincircuit.io/docs/guides/swaps/) (markdown: https://coincircuit.io/docs/guides/swaps.md) - [Telegram Bot Crypto Payments | CoinCircuit Docs](https://coincircuit.io/docs/guides/telegram-subscription-bot/) (markdown: https://coincircuit.io/docs/guides/telegram-subscription-bot.md) - [x402 Payments | CoinCircuit Docs](https://coincircuit.io/docs/guides/x402/) (markdown: https://coincircuit.io/docs/guides/x402.md) - [x402 API Monetization | CoinCircuit Docs](https://coincircuit.io/docs/guides/x402-api-monetization/) (markdown: https://coincircuit.io/docs/guides/x402-api-monetization.md) - [API Reference | CoinCircuit](https://coincircuit.io/api-reference/) (markdown: https://coincircuit.io/api-reference.md) - [Pricing | Low Fees from 0.5% | CoinCircuit](https://coincircuit.io/pricing/) (markdown: https://coincircuit.io/pricing.md) - [Crypto Payment Features | CoinCircuit](https://coincircuit.io/features/) (markdown: https://coincircuit.io/features.md) - [Use Cases | CoinCircuit](https://coincircuit.io/use-cases/) (markdown: https://coincircuit.io/use-cases.md) - [Accept Crypto Payments for Business | CoinCircuit](https://coincircuit.io/business/) (markdown: https://coincircuit.io/business.md) - [Crypto Invoicing | Professional Billing | CoinCircuit](https://coincircuit.io/products/invoices/) (markdown: https://coincircuit.io/products/invoices.md) - [Payment Links | No-Code Crypto Payments | CoinCircuit](https://coincircuit.io/products/payment-links/) (markdown: https://coincircuit.io/products/payment-links.md) - [Crypto Payouts API | Bulk Payouts | CoinCircuit](https://coincircuit.io/products/payouts/) (markdown: https://coincircuit.io/products/payouts.md) - [QR Code Crypto Payments | In-Person | CoinCircuit](https://coincircuit.io/products/qr-payments/) (markdown: https://coincircuit.io/products/qr-payments.md) - [Crypto POS Terminals | In-Store | CoinCircuit](https://coincircuit.io/products/pos/) (markdown: https://coincircuit.io/products/pos.md) - [White-Label Crypto Payments | Your Brand | CoinCircuit](https://coincircuit.io/products/whitelabel/) (markdown: https://coincircuit.io/products/whitelabel.md) - [Crypto Payments in Nigeria | Settle to NGN | CoinCircuit](https://coincircuit.io/nigeria/) (markdown: https://coincircuit.io/nigeria.md) - [Crypto Payment Infrastructure for Africa | CoinCircuit](https://coincircuit.io/africa/) (markdown: https://coincircuit.io/africa.md) - [Frequently Asked Questions | CoinCircuit](https://coincircuit.io/faq/) (markdown: https://coincircuit.io/faq.md) - [Security | CoinCircuit](https://coincircuit.io/security/) (markdown: https://coincircuit.io/security.md) - [About CoinCircuit | Crypto Payment Infrastructure for Africa](https://coincircuit.io/about/) (markdown: https://coincircuit.io/about.md) - [Ambassador Program | Scale with CoinCircuit](https://coincircuit.io/ambassador/) (markdown: https://coincircuit.io/ambassador.md) - [Ambassador Terms | CoinCircuit](https://coincircuit.io/ambassador/terms/) (markdown: https://coincircuit.io/ambassador/terms.md) - [AML Policy | CoinCircuit](https://coincircuit.io/aml/) (markdown: https://coincircuit.io/aml.md) - [Blog & Articles | CoinCircuit](https://coincircuit.io/blog/) (markdown: https://coincircuit.io/blog.md) - [Brand Assets | CoinCircuit](https://coincircuit.io/brand/) (markdown: https://coincircuit.io/brand.md) - [Careers at CoinCircuit | CoinCircuit](https://coincircuit.io/careers/) (markdown: https://coincircuit.io/careers.md) - [Brand Designer | Careers | CoinCircuit](https://coincircuit.io/careers/brand-designer/) (markdown: https://coincircuit.io/careers/brand-designer.md) - [Marketing & Growth | Careers | CoinCircuit](https://coincircuit.io/careers/marketing-growth/) (markdown: https://coincircuit.io/careers/marketing-growth.md) - [API Changelog | CoinCircuit](https://coincircuit.io/changelog/) (markdown: https://coincircuit.io/changelog.md) - [Community | CoinCircuit](https://coincircuit.io/community/) (markdown: https://coincircuit.io/community.md) - [Contact CoinCircuit](https://coincircuit.io/contact/) (markdown: https://coincircuit.io/contact.md) - [Cookie Policy | CoinCircuit](https://coincircuit.io/cookies/) (markdown: https://coincircuit.io/cookies.md) - [Privacy Policy | CoinCircuit](https://coincircuit.io/privacy/) (markdown: https://coincircuit.io/privacy.md) - [Compliance: Crypto Address and Transaction Screening | CoinCircuit](https://coincircuit.io/products/compliance/) (markdown: https://coincircuit.io/products/compliance.md) - [System Status | CoinCircuit](https://coincircuit.io/status/) (markdown: https://coincircuit.io/status.md) - [Terms of Service | CoinCircuit](https://coincircuit.io/terms/) (markdown: https://coincircuit.io/terms.md) - [Accept Binance Pay at Checkout | CoinCircuit | CoinCircuit Blog](https://coincircuit.io/blog/binance-pay/) (markdown: https://coincircuit.io/blog/binance-pay.md) - [Crypto Payments in Nigeria: Why Your Business Should Accept Crypto | CoinCircuit Blog](https://coincircuit.io/blog/accept-crypto-payments-nigeria/) (markdown: https://coincircuit.io/blog/accept-crypto-payments-nigeria.md) - [Crypto Payments Across Africa: Five Markets, Five Payment Stacks | CoinCircuit Blog](https://coincircuit.io/blog/crypto-payments-africa/) (markdown: https://coincircuit.io/blog/crypto-payments-africa.md) - [Stablecoins vs CBDCs: What the Data Says for African Fintech Builders | CoinCircuit Blog](https://coincircuit.io/blog/stablecoins-vs-cbdcs/) (markdown: https://coincircuit.io/blog/stablecoins-vs-cbdcs.md) - [The Multi-Chain Merchant: Why Your Customers Are on Different Blockchains | CoinCircuit Blog](https://coincircuit.io/blog/multi-chain-merchant-conversion-rates/) (markdown: https://coincircuit.io/blog/multi-chain-merchant-conversion-rates.md) - [How to Sign a Gasless Stablecoin Payment | CoinCircuit Blog](https://coincircuit.io/blog/how-to-sign-gasless-payment/) (markdown: https://coincircuit.io/blog/how-to-sign-gasless-payment.md) - [x402: How to Accept Payments from AI Agents on Your API | CoinCircuit Blog](https://coincircuit.io/blog/x402-machine-to-machine-payments/) (markdown: https://coincircuit.io/blog/x402-machine-to-machine-payments.md) - [The Agentic Web: Why AI Assistants Need Crypto Rails to Function | CoinCircuit Blog](https://coincircuit.io/blog/ai-assistants-crypto-rails/) (markdown: https://coincircuit.io/blog/ai-assistants-crypto-rails.md) --- # Crypto Payment Infrastructure for Africa | CoinCircuit > Crypto payment infrastructure for African business and AI agents. Accept crypto payments, automate global payouts, and settle in fiat or stablecoins. Source: https://coincircuit.io/ Markdown: https://coincircuit.io/index.md # Crypto paymentsbuilt for scale Crypto payment infrastructure to grow your revenue, from your first transaction to your billionth.Crypto payment infrastructure to grow your revenue, from your first transaction to your billionth. Accept payments anywhere, convert currencies instantly, and pay out across borders. [Get started](https://dashboard.coincircuit.io/signup) Markets [All pairs](https://dashboard.coincircuit.io/signup) *Bitcoin* BTC USD $96,420.00 *Tether* USDT $1.00 +0.00% *USD Coin* USDC *Ethereum* ETH $3,245.50 *Solana* SOL $198.42 *TelefyTech* *Bachs* *Nomba* *Binance* *Cencori* *Circle* *WalletConnect* *Pasabet* *Syncgram* *FSTL* *De Santiago* *VanityIsland* *SoleCapsule* ## Reach Every Market 560M+ people hold crypto. We give you the infrastructure to reach them. Revenue Growth $3.01M +119% CoinCircuit merchants see average order values 25% higher on crypto transactions than fiat. Q1 Q2 Q3 Q4 *Global payment network* ## Core Features Checkout, invoices, QR payments, payouts, on and off ramp, exchange checkout, and deposit accounts. All of it available through the API, on every major blockchain. [View all capabilities](https://coincircuit.io/features/)[ ### Crypto Checkout Accept crypto payments with branded checkout pages or payment links created straight from the API. Learn more 200.00 USDT $200.00 Network BSC (BEP-20) *QR Code* BSC (BEP-20) address 0xb50837139CD9339d114fd170391c3061c7b292Ee Expires In 09:45 Confirmations 0 from 6 ](https://coincircuit.io/products/payment-links/)[ ### On & Off Ramp Instantly swap between crypto and fiat currencies at transparent rates. Instant Swap You pay *USDT* Balance $3,721.56 You receive NGN 163,500.00 Exchange rate 1 USDT = 1,635.00 NGN Swap USDT for NGN ](https://coincircuit.io/features/)[ ### QR Payments Accept crypto payments in retail stores. Every payment page comes with a downloadable QR code your customers can scan at the counter. Coffee & Co. Scan to pay *Payment QR code* pay.coincircuit.io/coffee ](https://coincircuit.io/products/qr-payments/)[ ### Payouts Send stablecoin and fiat payouts, to wallets or bank accounts, in a single API call. Recent payouts Batch of 250 Asset Recipient Amount Status TQmzR4…k9Vp 12,500.00 Completed 9102 8433 71 540,000.00 *USDC* 0x84A9…3F1d 8,240.50 8842 1097 55 210,500.00 Processing TXk8Jd…mR7d 1,860.75 ](https://coincircuit.io/products/payouts/)[ ### Invoices Recurring payments and subscriptions in crypto. Create, send, and track every invoice. *Invoices*](https://coincircuit.io/products/invoices/)[ ### Pay with Exchange Direct integrations with major exchanges. Customers can pay straight from their exchange account. Select exchange 200 USDT *Binance* Binance *Coinbase* Coinbase *KuCoin* KuCoin *Busha* Busha ](https://coincircuit.io/features/)[ ### Deposit Accounts Issue unique dedicated NGN virtual accounts and static deposit addresses across multiple blockchains for your users. Deposit account Customer #4821 NGN virtual account Bank transfer Static deposit addresses *TRX* Tron TQmzR4hJ…k9Vp *BNB* BSC 0x84A9c2…3F1d *SOL* Solana 9wXqLmDe…Fh2b ](https://coincircuit.io/features/) Use cases ## Built to serve businesses across multiple sectors [See all use cases](https://coincircuit.io/use-cases/) [*Two brushed metal arches over a dotted world map, with a USDT coin crossing between them on a trail of light* B2B settlement ### Cross-Border Payments Get paid by customers abroad and settle in your local currency or stablecoins. ](https://coincircuit.io/use-cases/#cross-border-payments)[*A brushed metal shopping bag lit from within, with USDT, USDC and Bitcoin coins falling into it* Online and in store ### Ecommerce & Retail Add crypto to your checkout, online or at the counter. ](https://coincircuit.io/use-cases/#ecommerce)[*Machined metal dice and a roulette wheel tumbling beside USDT and Bitcoin coins* High frequency ### iGaming Credit deposits in seconds, pay winnings out just as fast. ](https://coincircuit.io/use-cases/#igaming)[*A glowing geodesic cage around a blue Base disc, releasing a USDC coin* Agentic payments ### AI Agents & Autonomous Commerce Let software pay for what it uses, with no human in the loop. ](https://coincircuit.io/use-cases/#ai-agents) ## Global Checkout Accept multiple crypto assets across every major blockchain. Settle in the stablecoin or local currency of your choice. 1 ### Select currency 50+ supported options 2 ### Scan and pay Wallet address and QR code 3 ### Confirmed On-chain confirmation 4 ### Settlement Settled to your account *Coincircuit* CoinCircuit [Sign Up](https://dashboard.coincircuit.io/signup) # Select Currency ₦30,000 Select asset, then choose network You pay network fee 01:00:00 *bsc* Proceed to Payment Step 1 of 4 # Built for developers REST API, webhooks, and SDKs for Node, Python, Go, and PHP. Plus a prompt library so any AI coding agent can one-shot your integration. [Read the Docs](https://coincircuit.io/api-reference/) MCP Server AI Agents Sub-50ms API Webhooks \>\_ example.ts ``` TypeScript SDK1import { CoinCircuit } from "@coincircuit/sdk";23const coincircuit = new CoinCircuit({ apiKey: process.env.KEY! });45const session = await coincircuit.createPayment({6 amount: 100,7 currency: "USD",8 chain: "ethereum",9 asset: "USDT",10 customer: { email: "test@test.com" }11}); ``` TS 5.0 ## Multiple Blockchains Supported Bitcoin BNB Chain Ethereum Litecoin Polygon Avalanche ## A payment engine you can trust. Built to the standard of regulated financial infrastructure. Every credential isolated, every transaction verified, every access audited. ### Data Privacy First All user data processed following global privacy and data protection best practices. ### Secure by Default Endpoints, keys, and credentials follow security best practices. ### Access Control Granular access controls and role-based permissions across your team, keys, and integrations. ### Compliance Built-in KYC/AML screening following industry-standard data protection protocols. ### Fraud Detection Real-time AML screening and anomaly detection on every transaction. ### Continuous Monitoring 24/7 automated threat detection with full audit logs and alerting. *CoinCircuit security infrastructure* ## Ready when you are. Start in minutes. Scale to millions. Same platform, same API. Slide to unlock access [DocsIntegration guides](https://coincircuit.io/docs/) [APIReference manual](https://coincircuit.io/api-reference/) [Support24/7 assistance](https://coincircuit.io/contact/) [FAQsCommon questions](https://coincircuit.io/faq/) ## Start accepting crypto today. [Get Started](https://dashboard.coincircuit.io/signup) [Read the Docs](https://coincircuit.io/docs/) --- # Agentic Payment Infrastructure | CoinCircuit AI > CoinCircuit's AI-powered payment layer for autonomous agents. Enable AI to send, receive, and settle crypto payments programmatically via MCP. Source: https://coincircuit.io/ai/ Markdown: https://coincircuit.io/ai.md # Agentic Crypto Payment Infrastructure The first payment infrastructure built for autonomous systems. Build agentic workflows and accept payments from AI agents using our MCP server and infrastructure. ## Embedded into Your Workflow CoinCircuit embeds AI agents directly into your operations, reconciling transactions, flagging anomalous patterns, and generating settlement reports without any manual work. 30+ Built-in tools. Less than 200ms Response time. 24/7 Autonomous ops. ## Key Capabilities ### MCP-Native Integration Plug in once via the Model Context Protocol. Your agent can query balances, create invoices, initiate payments, pull transaction history, and more, all natively. ### Autonomous Execution Workflows execute on their own. From invoice creation to settlement alerts, your agent handles the full payment lifecycle end to end. ### Automatic Reporting Every transaction is scored, classified, and surfaced as a clean report. Your team sees what matters, automatically. ## Your Payment AI Agent Chat with CoinCircuit's AI agent to manage payments, create invoices, and get transaction insights. ## AI That Understands Your Business Every transaction, payout, and customer interaction that flows through CoinCircuit is observed, reasoned about, and acted on by intelligent agents. From real-time insights to automated operations, AI works in the background so your team can focus on growth. --- # x402 Protocol for AI Agents | CoinCircuit > Accept payments from AI agents on your API natively. EIP-3009, Permit2, and Solana gasless signing schemes. Source: https://coincircuit.io/products/x402/ Markdown: https://coincircuit.io/products/x402.md Agentic Web # The x402 Protocol for AI Agent Payments Accept gasless stablecoin payments on your API. No minimums, no KYC, no human in the loop. [Start Building Free](https://dashboard.coincircuit.io/signup) [Read the Guide](https://coincircuit.io/blog/x402-machine-to-machine-payments/) ## How x402 Works x402 builds on the HTTP 402 Payment Required status code. Your server controls the session, while the agent signs the transaction off-chain. 1 The agent requests access. Your server creates a session via CoinCircuit and responds with a 402, including deposit details. 2 The agent signs a gasless payment (EIP-3009, Permit2, or Solana) and hands the signed payload back to your server. 3 Your server submits the payload to CoinCircuit. We settle it on-chain, cover the gas fees, and you unlock the resource. x402\_handshake.http ``` 1// 1. Agent requests your premium resource2GET /api/premium-data34// 2. Your server returns HTTP 402 with CoinCircuit session5HTTP/1.1 402 Payment Required6{7 "paymentRequired": {8 "chain": "base",9 "asset": "USDC",10 "amount": "1000000",11 "depositAddress": "0xabc...def"12 }13}1415// 3. Agent signs EIP-3009 gasless payment and POSTs it back16POST /api/premium-data/pay17{18 "scheme": "eip3009",19 "payload": {20 "from": "0xAgent...",21 "value": "1000000",22 "signature": "0xabcd..."23 }24} ``` ## Protocol Architecture ### EIP-3009 Supported Native gasless transfers for USDC on Base and Arbitrum. The agent signs, you submit, we cover the gas. ### Permit2 Integrated Support for USDT and other ERC-20 tokens via Uniswap's universal Permit2 architecture. ### Solana Fee Payer Native fee abstraction on Solana for sub-second machine payments. ### Pre-Validation Dry-run signatures and timestamps via our verify endpoint before touching the blockchain. ## Why Support x402? Purpose-built for autonomous software that needs to pay for resources. ### No Human In The Loop No 2FA, no CAPTCHAs, no bank logins. Built for pure machine-to-machine automation. ### Low Fees Agents pay fractions of a dollar per API call, below the minimum thresholds of traditional card processors. ### MCP Native Expose your paid tools to the growing Model Context Protocol ecosystem easily. ### Instant Settlement Settles on-chain in under 2 seconds. The agent pays, the resource unlocks immediately. ### Monetize Your API Automatically Build native AI monetization for your infrastructure using x402 and MCP. [Create API Key](https://dashboard.coincircuit.io/signup) [View Developer Tools](https://coincircuit.io/docs/) --- # Developer Docs | CoinCircuit > Guides and tutorials to integrate crypto payments fast. Learn setup, webhooks, SDKs, and best practices to go live quickly. Source: https://coincircuit.io/docs/ Markdown: https://coincircuit.io/docs.md Developer Documentation # Build with CoinCircuit Everything you need to integrate CoinCircuit. Designed for developers, built for scale. [ Full Ref ### API Documentation Complete endpoints, request examples, and schemas. - Endpoints - MCP - Error Codes - Response Types](https://coincircuit.io/api-reference/)[ 10 min read ### Webhooks Real-time event notifications and security. - Events - Signatures - Retries - Best Practices](https://coincircuit.io/api-reference/?tab=webhooks)[ Latest ### Changelog New features, fixes, and breaking changes across every release. - Releases - Deprecations - Migration](https://coincircuit.io/api-reference/?tab=changelog) ## Why Developers Choose Us Built for engineers who care about performance, security, and developer experience. ### Lightning Fast Most API calls respond in under 100ms. ### Secure by Default Encrypted in transit and at rest, with signed webhooks. ### Developer Friendly Clear responses, helpful errors, and SDKs. ### Tested & Reliable Test everything in the sandbox before you go live. ### Ready to Start Building? Join developers worldwide using CoinCircuit to power their crypto payments. [Get Started Now](https://coincircuit.io/api-reference/) [Contact Support](https://coincircuit.io/contact/) --- # Integration Guides | CoinCircuit > Step-by-step crypto payment integration guides for e-commerce, mobile apps, retail, and more. Get your first payment live in minutes. Source: https://coincircuit.io/docs/guides/ Markdown: https://coincircuit.io/docs/guides.md Integration Use Cases # Integrate Anywhere From online stores to physical locations, see how businesses across industries use CoinCircuit to accept crypto payments. [Start Building](https://coincircuit.io/api-reference/?tab=quickstart) [API Reference](https://coincircuit.io/api-reference/) ## Integration Methods Flexible solutions tailored to your tech stack. [ ### Dynamic API For custom, programmatic checkouts. - Unique addresses per order - Webhooks - Full control Click to view demo ](https://checkout.coincircuit.io/demo/pay) ### Static QR For physical stores & simple payments. - No code needed - Printable - Instant setup [ ### AI Chat Bots For social commerce automation. - Telegram/WhatsApp - No website needed - Auto-tracking](https://t.me/CoincircuitBot) ## Real-World Applications See how businesses across industries integrate crypto payments Easy Dynamic Checkout API ### E-Commerce Integrate crypto payments directly into your online store's checkout flow. Seamless checkout integration Real-time payment updates Automatic order fulfillment Multi-currency support [Learn more](https://coincircuit.io/api-reference/?tab=quickstart) Medium SDK Integration ### Mobile Apps Native crypto payments for iOS and Android applications. Native SDK integration In-app payment flows Push notifications Subscription support Static Checkout ### Hospitality Enable guests to pay for bookings and amenities securely. Booking system integration QR code room payments Multi-property support POS integration Very Easy ### Retail Stores Accept crypto at physical checkout counters instantly. Static QR codes Point-of-sale terminals Instant confirmations Digital receipts Dynamic API ### Events Sell tickets and passes with crypto options for high-volume sales. High-volume capability NFT ticket support Event-specific pricing Instant delivery ### Gaming In-game purchases, currencies, and battle passes. Microtransactions In-game currency Battle pass payments Global accessibility ### Ready to Integrate? Start accepting crypto payments in minutes with our simple integration guides. [Get Started Now](https://coincircuit.io/api-reference/?tab=quickstart) [View Full API Docs](https://coincircuit.io/api-reference/) --- # Authentication | CoinCircuit Docs > Authenticate requests, handle rate limits and errors. Source: https://coincircuit.io/docs/guides/authentication/ Markdown: https://coincircuit.io/docs/guides/authentication.md Authenticate every request by sending your API key in the `x-api-key` header. ```http x-api-key: your_api_key_here ``` ## API keys Generate keys in the dashboard under **Developer > API Keys**. Use test keys against the sandbox base URL and live keys against production. Treat keys like passwords and keep them out of public repositories. ## Rate limiting The API allows **100 requests per minute**. Exceeding the limit returns a `429 Too Many Requests` response. ## Pagination List endpoints accept `page` (default 1) and `size` (default 10, max 100) query parameters. Paginated responses include a `meta` object: ```json "meta": { "page": 1, "size": 10, "total": 42, "totalPages": 5 } ``` ## Error handling The API uses standard HTTP status codes to signal success or failure. | Status | Meaning | | :--- | :--- | | 400 | Invalid or malformed request | | 401 | Invalid or missing authentication | | 404 | Resource not found | | 409 | Resource conflict | | 503 | Service unavailable | Error responses share one shape: ```json { "success": false, "timestamp": "2026-01-23T23:33:55.685Z", "path": "/api/v1/payments", "method": "POST", "error": "Unauthorized", "message": "Unauthorized" } ``` --- # Payments | CoinCircuit Docs > Accept one-time crypto payments online. Source: https://coincircuit.io/docs/guides/checkout-sessions/ Markdown: https://coincircuit.io/docs/guides/checkout-sessions.md ## API reference - POST `/api/v1/payments`: [Create a payment](https://coincircuit.io/api-reference/#tag/payments/POST/api/v1/payments) - GET `/api/v1/payments/reference/{reference}`: [Retrieve a payment](https://coincircuit.io/api-reference/#tag/payments/GET/api/v1/payments/reference/{reference}) - GET `/api/v1/payments`: [List payments](https://coincircuit.io/api-reference/#tag/payments/GET/api/v1/payments) A payment is a single charge for a set amount. You create it in fiat, and CoinCircuit prices it in the crypto your customer picks, locks the rate, and collects the funds. The customer pays in any supported asset, CoinCircuit confirms it on the blockchain, and your server gets a webhook the moment it clears so you can fulfil the order. ![CoinCircuit hosted checkout page](https://coincircuit.io/images/features/checkout-sessions.webp) ## How it works 1. Create a payment session with `POST /api/v1/payments`. 2. Redirect the customer to the checkout page. 3. Wait for a payment webhook event. 4. Verify the payment status. 5. Fulfil the order. ## Request fields | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `title` | string | Yes | Title shown on the checkout page. | | `description` | string | Yes | Description of what the payment is for. | | `amount` | string | Yes | Fiat amount as a string, e.g. `"10000.00"`. | | `currency` | string | Yes | `NGN` or `USD`. | | `customer` | object | Yes | `email` is required. `firstName`, `lastName`, and `phone` are optional. | | `asset` | string | No | Cryptocurrency to accept: `BTC`, `ETH`, `USDT`, `USDC`, `SOL`, `BNB`, or `TRX`. Omit to let the customer choose. | | `chain` | string | No | Network to accept it on: `bitcoin`, `ethereum`, `solana`, `bsc`, `tron`, `base`, or `arbitrum`. | | `successUrl` / `cancelUrl` | string | No | HTTPS redirect URLs after payment or cancellation. | | `webhookUrl` | string | No | HTTPS URL that receives webhook events for this session. | | `feePaidBy` | string | No | Who pays the network fee: `customer` or `merchant`. Defaults to your dashboard setting. | | `metadata` | object | No | Key-value data stored on the session and returned in webhooks. | You can also create a one-off payment from the dashboard: ![Creating a payment from the dashboard](https://coincircuit.io/images/features/checkout-create.webp) Each session has a detail view with its status, reference, payment link, and transactions: ![Payment details](https://coincircuit.io/images/features/checkout-details.webp) ## Webhook events | Event | Description | | :--- | :--- | | `transaction.received` | Transaction has been detected. | | `transaction.confirmed` | Transaction has been confirmed on the blockchain. | | `payment.completed` | Payment completed successfully. | | `payment.partial` | Partial payment received. | | `payment.underpaid` | Payment amount was insufficient. | | `payment.expired` | Payment session expired. | ## Use cases - E-commerce and digital product checkout - Pay-per-use billing and top-ups - Single payments with a known amount > Store your internal order ID in `metadata` to receive it in webhook events. --- # Crypto Payouts | CoinCircuit Docs > Send USDT payouts to any crypto wallet. Source: https://coincircuit.io/docs/guides/crypto-payouts/ Markdown: https://coincircuit.io/docs/guides/crypto-payouts.md Tags: Payouts, Balance, Webhooks Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me add crypto payouts to my existing application using CoinCircuit. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_endpoint` with method `post` and path `/api/v1/recipients` for the recipient creation schema. - Call `get_endpoint` with method `post` and path `/api/v1/payouts` for the payout creation schema. - Call `get_schema` with name `PayoutSuccessWebhookDto` for the payout.success webhook payload. - Call `get_schema` with name `PayoutFailedWebhookDto` for the payout.failed webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have an application that needs to pay users in crypto (USDT) from my CoinCircuit merchant balance to their wallet addresses. Use cases: vendor payments, creator payouts, rewards, or any disbursement to external wallets. ## What I Need You to Implement ### 1. Save a payout recipient Before you can send a payout, the recipient wallet address must be saved. **Endpoint:** `POST /api/v1/recipients` *(Call `get_endpoint` with method `post`, path `/api/v1/recipients` in the CoinCircuit MCP for the full request/response schema.)* **Required fields:** - `type` (string) - `"crypto_address"` for a wallet, or `"ngn_bank_account"` for a bank account - `details` (object) - for `crypto_address`: `{ chain, address }`. `chain` is one of `"bsc"`, `"tron"`, `"solana"`, `"base"`, or `"ethereum"`; `address` is the wallet address. **Optional fields:** - `label` (string) - friendly name, e.g. "Alice's BSC wallet" - `isDefault` (boolean) - make this the default recipient for its type **Example request body:** ```json { "type": "crypto_address", "label": "Alice's BSC wallet", "details": { "chain": "bsc", "address": "0xRecipientAddress" } } ``` **Response (201):** Returns the saved recipient with an `id` (UUID). You'll use this `id` as the `recipientId` when creating payouts. If a matching recipient already exists, the existing one is returned instead of a duplicate. **Errors:** 400 if the details are invalid or the type is unsupported. ### 2. Create crypto payout **Endpoint:** `POST /api/v1/payouts` *(Call `get_endpoint` with method `post`, path `/api/v1/payouts`, section `request` in the CoinCircuit MCP for the exact request body with all field validations.)* **Required fields:** - `method` (string) - `"crypto"` (or `"fiat"` for bank transfers) - `currency` (string) - `"USDT"` or `"NGN"` - `amount` (string) - amount to send as a string, e.g. `"100.00"` - `recipientId` (string, UUID) - the saved crypto address ID from step 1 **Optional fields:** - `narration` (string) - description, e.g. "Creator payout - March" - `reference` (string) - your unique idempotency reference. **Duplicate references are rejected.** If omitted, CoinCircuit generates one. **Example request body:** ```json { "method": "crypto", "currency": "USDT", "amount": "100.00", "recipientId": "addr_123456789_abcdef", "narration": "Creator payout - March 2026", "reference": "PAYOUT-MARCH-ALICE-001" } ``` **Response (201):** Returns the payout object: - `data.id` - payout UUID - `data.status` - starts as `"pending"`, transitions to `"processing"`, `"success"`, or `"failed"` - `data.amount` - amount the recipient gets - `data.fee` - fee charged - `data.total` - total debited from your balance (amount + fee) - `data.currency` - `"USDT"` - `data.reference` - your reference or auto-generated - `data.txHash` - blockchain transaction hash (populated after success) - `data.recipient` - object with `type: "crypto_address"` and `details: { chain, address }` - `data.conversion` - if cross-currency, includes `from`, `to`, `rate`, `convertedAmount`. Null if same currency. - `data.failureReason` - populated if failed *(Call `get_endpoint` with method `post`, path `/api/v1/payouts`, section `success` in the CoinCircuit MCP for the complete response schema.)* **Errors:** 400 (validation error, insufficient balance, daily limit exceeded), 404 (recipient address not found) ### 3. Track payout status via webhooks Payouts are async. The API returns immediately with `"pending"` status. Wait for webhooks: *(Call `get_schema` with name `PayoutSuccessWebhookDto` in the CoinCircuit MCP for the full payout.success webhook payload. Call `get_schema` with name `PayoutFailedWebhookDto` for the failure payload.)* **Payout events** (envelope: `{ event: string, data: { payout: PayoutObject } }`): - `payout.created` - payout submitted and processing - `payout.success` - funds delivered on-chain. `data.payout.txHash` has the transaction hash, `data.payout.completedAt` has the timestamp. - `payout.failed` - payout failed. `data.payout.failureReason` explains why. Funds are returned to your balance. ## Constraints - `amount` is a string (e.g. `"100.00"`) - Duplicate `reference` values are rejected. Use unique references for idempotency. - Crypto payouts support USDT (on Tron, BSC) and USDC (on Base). - Payouts are async. Never assume success from the API response. Always wait for webhooks. - Fiat payouts go only to the merchant's own bank account. Use crypto payouts for third-party disbursements. --- # Customer Deposit Accounts | CoinCircuit Docs > Give each customer reusable crypto addresses and a bank account to fund their balance. Source: https://coincircuit.io/docs/guides/customer-deposit-accounts/ Markdown: https://coincircuit.io/docs/guides/customer-deposit-accounts.md Tags: Deposits, Webhooks, Customers Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me add CoinCircuit deposit accounts to my existing application, so each of my customers gets reusable pay-in details that fund my balance. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_api_overview` in the CoinCircuit MCP for base URLs, auth method, and available features. - Call `search_api` with feature `Deposits` to list every deposit endpoint. - Call `get_endpoint` with method `post` and path `/api/v1/deposits/accounts` for the account creation schema. - Call `get_endpoint` with method `post` and path `/api/v1/deposits/accounts/{id}/identities` for the identity (crypto address / virtual account) schema. - Call `get_endpoint` with method `get` and path `/api/v1/deposits` for the deposits list schema. - Call `get_schema` with name `DepositDto` for the deposit object used by `GET /api/v1/deposits/{id}` and the deposit webhooks. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL (production):** `https://api.coincircuit.io` - **Base URL (sandbox):** `https://sandbox-api.coincircuit.io` - **Auth:** Pass your API key in the `x-api-key` header on every request. ## Project Context I want each of my customers to have a fixed place to send me funds: a permanent crypto address on each blockchain, and a Nigerian bank account number for fiat transfers. The customer reuses the same details for every deposit, and CoinCircuit detects each one, attributes it to that customer, and credits it to my balance. The flow: 1. Create a deposit account for a customer. 2. Issue one or more pay-in identities on it (a crypto address on a blockchain, or an NGN virtual account). 3. Show the address or account number to the customer. 4. Listen for deposit webhooks and credit the customer in my own system. ## What I Need You to Implement ### 1. Create a deposit account **Endpoint:** `POST /api/v1/deposits/accounts` *(Call `get_endpoint` with method `post`, path `/api/v1/deposits/accounts` in the CoinCircuit MCP for the full request/response schema.)* - `customerId` (string, optional) - the customer this account belongs to. Omit it to create a deposit account for your own (parent) balance. **Response (201):** Returns the deposit account with an `id`. Use that `id` to issue identities in the next step. ### 2. Issue a pay-in identity **Endpoint:** `POST /api/v1/deposits/accounts/{id}/identities` *(Call `get_endpoint` with method `post`, path `/api/v1/deposits/accounts/{id}/identities` in the CoinCircuit MCP for the exact request body.)* There are two identity types: - **Static crypto address:** `{ "type": "static_deposit_address", "chain": "bsc" }`. `chain` is one of `bitcoin`, `ethereum`, `solana`, `bsc`, `tron`, `base`, `arbitrum`. Returns a permanent address on that blockchain. - **NGN virtual account:** `{ "type": "ngn_virtual_account", "bvn": "12345678901", "currency": "NGN" }`. Returns a bank account number the customer can transfer to. `bvn` is your 11-digit merchant BVN. Issue both on the same account so a customer can fund by crypto or by bank transfer. ### 3. Show the details to your customer Display the crypto address (with its blockchain and a QR code) or the bank account number. The customer reuses the same details every time; do not issue a new identity per deposit. ### 4. Handle deposit webhooks *(Call `get_schema` with name `DepositDto` in the CoinCircuit MCP for every field in the deposit payload.)* The deposit webhook payload is `{ event, data }`, where `data` is the deposit object: - `data.id` - the deposit id - `data.type` - `"crypto"` or `"fiat"` (one of `data.crypto` / `data.fiat` is populated, the other is null) - `data.currency`, `data.amount`, `data.fee` - decimal strings - `data.depositAccountId` and `data.customerId` - which account and customer the deposit belongs to (`customerId` is null for your parent account) - `data.status` and `data.completedAt` **Deposit events:** - `deposit.processing` - a deposit was detected and is being processed. - `deposit.completed` - the deposit cleared and was credited to your balance. **Credit your customer in your own system here.** - `deposit.failed` - the deposit was rejected by a compliance check. **Webhook security:** verify the HMAC-SHA256 signature in the `x-coincircuit-signature` header, and use `x-coincircuit-delivery-id` for idempotency. ### 5. List and reconcile deposits - List deposits with `GET /api/v1/deposits`. - Get one with `GET /api/v1/deposits/{id}`. - List a customer's accounts with `GET /api/v1/deposits/accounts/customer/{customerId}`, or your own with `GET /api/v1/deposits/accounts/parent`. ## Constraints - A crypto address and a bank account number are permanent per customer. Reuse them; never issue a new identity per deposit. - Match a deposit to a customer with `data.customerId`. A null `customerId` means it landed in your own parent account. - NGN virtual accounts require your merchant BVN and settle in NGN. - Credit your customer on `deposit.completed`, not `deposit.processing`. - Amounts and fees are decimal strings. --- # Deposit Accounts | CoinCircuit Docs > Static deposit addresses and NGN virtual accounts per customer. Source: https://coincircuit.io/docs/guides/deposit-accounts/ Markdown: https://coincircuit.io/docs/guides/deposit-accounts.md ## API reference - POST `/api/v1/deposits/accounts`: [Create a deposit account](https://coincircuit.io/api-reference/#tag/deposits/POST/api/v1/deposits/accounts) - POST `/api/v1/deposits/accounts/{id}/identities`: [Issue a deposit identity](https://coincircuit.io/api-reference/#tag/deposits/POST/api/v1/deposits/accounts/{id}/identities) - GET `/api/v1/deposits`: [List deposits](https://coincircuit.io/api-reference/#tag/deposits/GET/api/v1/deposits) A deposit account gives one customer a fixed place to send you money again and again: a permanent crypto address on each blockchain, and a bank account number for fiat transfers. The customer reuses the same details for every payment, and CoinCircuit detects each deposit, ties it to that customer, and credits it to your balance. ![How deposit accounts work: each account issues static crypto addresses and an NGN virtual account, and every deposit is routed to your balance](https://coincircuit.io/images/features/deposit-accounts.png) ## How it works 1. Create a deposit account with `POST /api/v1/deposits/accounts` (pass a `customerId`, or omit it for your parent account). 2. Issue an identity with `POST /api/v1/deposits/accounts/{id}/identities`: a `static_deposit_address` on a chain, or an `ngn_virtual_account`. 3. Share the address or account number with your customer. 4. Track incoming funds with `GET /api/v1/deposits` and `GET /api/v1/deposits/{id}`. ## Identity fields | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `type` | string | Yes | `static_deposit_address` or `ngn_virtual_account`. | | `chain` | string | Conditional | Required for a static address: `ethereum`, `solana`, `bsc`, `tron`, `base`, or `arbitrum`. | | `bvn` | string | Conditional | BVN of the account holder (11 digits). Required for an NGN virtual account. | | `currency` | string | Conditional | `NGN`. Used for virtual accounts. | ## Supported tokens Each static address accepts these tokens on its blockchain: | Blockchain | Tokens | | :--- | :--- | | Ethereum | ETH, USDT, USDC | | Solana | SOL, USDT, USDC | | BSC | BNB, USDT, USDC | | Tron | USDT, TRX | | Base | ETH, USDC | | Arbitrum | ETH, USDT, USDC | USDT and USDC deposits credit your balance in the same currency. Any other token is automatically converted to USDT and credited to your USDT balance. The deposit record keeps the original token and amount, with a `conversion` showing the rate and the USDT credited. ## Use cases - Neobanks giving each user a funding address - Customer wallets and account funding - Recurring inbound transfers and collections - Treasury and OTC desks aggregating from many senders > Static addresses are supported on Ethereum, Solana, BSC, Tron, Base, and Arbitrum. Because each identity is fixed per customer, you always know who sent what. --- # Donation / Tip Page | CoinCircuit Docs > Accept crypto donations or tips with a shareable page. Source: https://coincircuit.io/docs/guides/donation-page/ Markdown: https://coincircuit.io/docs/guides/donation-page.md Tags: Payment Pages, Payments, Frontend Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me add a crypto donation/tip page to my existing site using CoinCircuit. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_endpoint` with method `post` and path `/api/v1/payments/pages` in the CoinCircuit MCP for the full payment page creation schema. - Call `get_endpoint` with method `post` and path `/api/v1/payments` for the checkout session creation schema (needed for Option B). - Call `search_api` with feature `Payment Pages` to see all available payment page endpoints (create, update, delete, list). - Call `get_schema` with name `PaymentCompletedWebhookDto` for the payment.completed webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have a site and I'm adding a public page where supporters can donate any amount in crypto. ## What I Need You to Implement ### Option A: Payment Page (zero backend, simplest approach) CoinCircuit has hosted payment pages with open-amount input. One API call and you get a shareable URL. **Endpoint:** `POST /api/v1/payments/pages` *(Call `get_endpoint` with method `post`, path `/api/v1/payments/pages`, section `request` in the CoinCircuit MCP for the exact request body with all field types and validations.)* **Required fields:** - `title` (string, 1-100 chars) - e.g. "Support My Project" - `isActive` (boolean) - set to `true` - `currency` (string) - `"NGN"` or `"USD"` **Optional fields:** - `description` (string) - displayed on the page - `minAmount` (number) - minimum donation amount - `bankAccountIds` (array of strings) - associate bank accounts for fiat settlement **Example request:** ```json { "title": "Support My Project", "description": "Help me keep building open source tools", "isActive": true, "currency": "USD", "minAmount": 1 } ``` **Response (201):** Returns the payment page object: - `data.reference` - page reference - `data.url` - the hosted page URL (e.g. `https://checkout.coincircuit.io/static/1234567890`). Share this anywhere. *(Call `get_endpoint` with method `post`, path `/api/v1/payments/pages`, section `success` in the CoinCircuit MCP for the full response schema.)* No backend required. Share the URL on social media, your website, or anywhere. Donors enter any amount they choose. ### Option B: Custom branded donation page (full UI control) For full control over the design: 1. Build a frontend with an open amount input field 2. On "Donate" click, your backend creates a checkout session: **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `example` in the CoinCircuit MCP for a sample request.)* Required fields: `title`, `description`, `amount` (string), `currency`, `customer` (with at least `email`). Store donor info in `metadata`: ```json { "title": "Donation", "description": "Donation from Jane", "amount": "25.00", "currency": "USD", "customer": { "email": "jane@example.com" }, "metadata": { "donorName": "Jane", "message": "Keep up the great work!" }, "successUrl": "https://mysite.com/thanks" } ``` 3. Open the checkout SDK modal with the session `reference`, or redirect to `data.url` ### Webhook handler Listen for `payment.completed` to: - Display the donor on a public wall (read `data.session.metadata.donorName` and `data.session.metadata.message`) - Update a running donation total (read `data.session.amount` and `data.session.currency`) - Send a thank-you email (read `data.session.customer.email`) *(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP for every field available in the webhook payload.)* ### Updating or deleting a payment page *(Call `search_api` with feature `Payment Pages` in the CoinCircuit MCP to see all available endpoints: create, update, delete, list, and get by reference.)* - `PUT /api/v1/payments/pages/{reference}` - update title, description, or deactivate the page - `DELETE /api/v1/payments/pages/{reference}` - delete the page *(Call `get_endpoint` with method `put`, path `/api/v1/payments/pages/{reference}` in the CoinCircuit MCP for the update request schema.)* ## Constraints - Payment pages are the zero-code option for basic donation pages - For custom amounts, validate minimum amount server-side - Session `amount` is a string in fiat (e.g. `"25.00"`) - Use `metadata` to store donor info without needing CoinCircuit customer records - Supported currencies: NGN, USD --- # Dynamic Settlement | CoinCircuit Docs > Choose the currency each payment and deposit account is settled into. Source: https://coincircuit.io/docs/guides/dynamic-settlement/ Markdown: https://coincircuit.io/docs/guides/dynamic-settlement.md ## API reference - POST `/api/v1/payments`: [Create a payment](https://coincircuit.io/api-reference/#tag/payments/POST/api/v1/payments) - POST `/api/v1/deposits/accounts`: [Create a deposit account](https://coincircuit.io/api-reference/#tag/deposits/POST/api/v1/deposits/accounts) Price in one currency, let your customer pay in whichever token they hold, and choose the currency you end up with. Settlement currency is set per payment and per deposit account, so a single account can take NGN prices and hold USDT, or take USDT deposits from one customer and NGN from another. ## How it works 1. Set an account currency in the dashboard. Every payment settles into it unless you say otherwise. 2. Override it on a single payment by passing `settlementCurrency` to `POST /api/v1/payments`. 3. Override it for a deposit account by passing `settlementCurrency` to `POST /api/v1/deposits/accounts`. It applies to every deposit into that account. 4. Read `settlements.currency` on the payment to see what it settled into, and `settlements.net` for the amount credited. The currency is fixed when the payment is created. Changing your account currency later does not move a payment that is already open. `settlementCurrency` takes any supported balance, e.g. `USDT`. Deposit accounts also take `default`, where the deposited token decides. ## Pricing and settlement are separate `currency` is what you price in and what your customer sees. `settlementCurrency` is what you are paid in. They do not have to match. ```json POST /api/v1/payments { "amount": "10000.00", "currency": "NGN", "settlementCurrency": "USDT", "customer": { "email": "customer@example.com" } } ``` The customer is quoted 10,000 NGN, pays in the token they chose, and your USDT balance is credited. When the two currencies differ, `settlements.gross.conversionRate` records the rate used. ## Deposit accounts On `default`, the deposited token decides. Supported balances are credited directly, e.g. a USDT deposit credits your USDT balance. Other tokens are converted, e.g. an ETH deposit lands as USDT. Set a currency and the account decides instead: every deposit is settled into it, converting where needed. Your parent account is always `default`. ```json POST /api/v1/deposits/accounts { "customerId": "123e4567-e89b-12d3-a456-426614174000", "settlementCurrency": "USDC" } ``` ## Use cases - Pricing in local currency while holding stablecoins - Holding NGN for local payouts without managing conversions yourself - Giving each customer a deposit account that settles in the currency they fund you in > NGN has no on-chain token, so a crypto deposit into an NGN deposit account always converts. --- # E-Commerce Crypto Checkout | CoinCircuit Docs > Accept crypto at checkout with the embedded SDK and order webhooks. Source: https://coincircuit.io/docs/guides/ecommerce-checkout/ Markdown: https://coincircuit.io/docs/guides/ecommerce-checkout.md Tags: Checkout SDK, Webhooks, Node.js Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me integrate CoinCircuit crypto payments into my existing e-commerce website. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_api_overview` in the CoinCircuit MCP for base URLs, auth method, and available features. - Call `get_endpoint` with method `post` and path `/api/v1/payments` to get the full request/response schema for creating payment sessions. - Call `search_api` with query `webhook` and type `schemas` to get all webhook payload schemas. - Call `get_schema` with name `PaymentCompletedWebhookDto` for the exact payment.completed webhook payload. - Call `get_schema` with name `TransactionReceivedWebhookDto` for the transaction.received webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL (production):** `https://api.coincircuit.io` - **Base URL (sandbox):** `https://sandbox-api.coincircuit.io` - **Auth:** Pass your API key in the `x-api-key` header on every request. ## Project Context I have an e-commerce site and I'm adding crypto payments at checkout using CoinCircuit. The flow: 1. Customer clicks "Pay with Crypto" on my checkout page 2. My server creates a CoinCircuit payment session via `POST /api/v1/payments` 3. The embedded checkout modal opens on the frontend using the session `reference` 4. Customer pays, my server gets a webhook, and the order is fulfilled ## What I Need You to Implement ### 1. Server-side: Create a payment session **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `example` in the CoinCircuit MCP for a ready-to-use sample request.)* **Required fields:** - `title` (string) - e.g. "Order #1234" - `description` (string) - e.g. "Payment for order #1234" - `amount` (string) - fiat amount as a string, e.g. `"150.00"` (NOT a number) - `currency` (string) - `"NGN"` or `"USD"` - `customer` (object) - must include `email` (required). Optional: `firstName`, `lastName`, `phone` (E.164 format), `telegramId` **Optional fields:** - `asset` (string) - lock to a specific crypto: `"BTC"`, `"ETH"`, `"USDT"`, `"USDC"`, `"SOL"`, `"BNB"`, `"TRX"`. If omitted, the customer chooses on the checkout page. - `chain` (string) - lock to a specific blockchain: `"bitcoin"`, `"ethereum"`, `"solana"`, `"bsc"`, `"tron"`, `"base"`, `"arbitrum"`. If omitted, the customer chooses. - `metadata` (object) - store your internal `orderId` here for webhook reconciliation - `successUrl` (string) - redirect after successful payment (must be HTTPS) - `cancelUrl` (string) - redirect if customer cancels - `webhookUrl` (string) - per-session webhook URL override (must be HTTPS) - `feePaidBy` (string) - `"customer"` or `"merchant"`, controls who pays network gas fees. If omitted, uses your dashboard default. **Example request body:** ```json { "title": "Order #1234", "description": "2x Widget Pro", "amount": "150.00", "currency": "USD", "customer": { "email": "buyer@example.com", "firstName": "Jane", "lastName": "Smith" }, "metadata": { "orderId": "ORD-1234", "items": "2x Widget Pro" }, "successUrl": "https://mystore.com/order/1234/success", "cancelUrl": "https://mystore.com/cart" } ``` **Response (201):** Returns a session object. The key fields you need: - `data.reference` - pass this to the frontend checkout SDK - `data.url` - hosted checkout page URL (e.g. `https://checkout.coincircuit.io/pay/cs_ref_abc123`) - `data.payment.status` - starts as `"pending"` - `data.payment.address` - the deposit address (if asset/chain were specified) - `data.expiresAt` - ISO 8601 expiration timestamp *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `success` in the CoinCircuit MCP for the full response schema.)* **Error responses:** 400 (invalid input or unsupported asset/chain combo), 401 (bad API key) ### 2. Client-side: Embedded checkout Install the checkout SDK: ```bash npm install @coincircuit/checkout ``` Use `CoinCircuitCheckout` to open a modal with the session `reference` from the server response. Handle these callbacks: - `onPaymentComplete` - show success state, redirect to order confirmation - `onPaymentFailed` - show error, offer retry - `onClose` - user dismissed the modal without paying **Alternative:** Skip the SDK entirely and redirect the customer to `data.url` from the session response. This is the hosted checkout page and requires zero frontend code. ### 3. Webhook handler: Order fulfillment Set up an endpoint to receive CoinCircuit webhooks. *(Call `search_api` with query `payment webhook` and type `schemas` in the CoinCircuit MCP to list all payment and transaction webhook schemas. Then call `get_schema` on any specific one for full field details.)* **Payment events** (envelope: `{ event: string, data: { session: PaymentSession, failureReason?: string } }`): - `payment.completed` - full payment confirmed. The `data.session` object contains the full session with `payment.status: "completed"`, `payment.amountReceived`, and a `transaction` object with `txHash`, `chain`, `asset`, `fromAddress`, `toAddress`, `amount`, `explorerUrl`, `confirmations`. **This is your trigger to fulfill the order.** - `payment.partial` - customer sent crypto but not enough. `data.session.payment.amountReceived` shows what you got. The session stays open for more payments. - `payment.expired` - session expired before full payment. Cancel or hold the order. - `payment.underpaid` - session closed with less than the required amount. Check `data.session.payment.amountReceived` vs `data.session.payment.amount`. *(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP for every field in the payment.completed payload.)* **Transaction events** (envelope: `{ event: string, data: { session: PaymentSession } }`, the session includes a `transaction` field): - `transaction.received` - payment detected on-chain but unconfirmed. Good for showing "payment detected" UI. The `transaction` object has `status: "pending"`, `txHash`, `chain`, `asset`, `amount`, `fromAddress`, `toAddress`. - `transaction.confirmed` - payment confirmed on the blockchain. The `transaction` object has `status: "confirmed"`, `confirmations`, `confirmedAt`. *(Call `get_schema` with name `TransactionReceivedWebhookDto` or `TransactionConfirmedWebhookDto` in the CoinCircuit MCP for exact field details.)* **Webhook security:** - Verify the HMAC-SHA256 signature in the `x-coincircuit-signature` header using your webhook secret - Use the `x-coincircuit-delivery-id` header for idempotency (store processed delivery IDs and skip duplicates) **Key webhook fields for reconciliation:** - `data.session.reference` - matches the session you created - `data.session.metadata` - your `orderId` is here - `data.session.settlements.net.amount` - the amount you actually receive after all fees ## Constraints - `amount` is a **string** in fiat, not a number - Always verify webhook signatures before processing - Store the session `reference` alongside the order for reconciliation - Handle partial payments gracefully. If the session state is `"open"`, the customer can still make additional payments. If `"closed"`, no further payments are accepted. - `successUrl` and `cancelUrl` must be HTTPS - Supported currencies: NGN, USD. Supported assets: BTC, ETH, USDT, USDC, SOL, BNB, TRX. Supported chains: bitcoin, ethereum, solana, bsc, tron, base, arbitrum. --- # E-Commerce Plugins | CoinCircuit Docs > Accept crypto in your WooCommerce or OpenCart store with a plugin. Source: https://coincircuit.io/docs/guides/ecommerce-plugins/ Markdown: https://coincircuit.io/docs/guides/ecommerce-plugins.md Accept crypto payments in your online store with a CoinCircuit plugin. Install it, enter your API key and webhook secret, and your checkout takes crypto with order statuses updating automatically from signed webhooks. ## WooCommerce For WordPress stores running WooCommerce 7.0 or newer. Works with the classic checkout and checkout blocks. Shoppers pay in a CoinCircuit checkout that opens over your store's payment page, and orders move through Processing, On hold, Failed, and Refunded automatically. **[Download for WooCommerce](https://github.com/CoinCircuit/woo-commerce/releases/latest/download/coincircuit-woocommerce.zip)** 1. In WordPress, go to **Plugins > Add New > Upload Plugin** and upload the zip. 2. Activate **CoinCircuit for WooCommerce**. 3. Go to **WooCommerce > Settings > Payments > CoinCircuit**, enable it, and enter your API key and webhook secret. 4. Add your store's webhook endpoint in the dashboard: `https://your-site.com/wp-json/coincircuit/v1/webhook` Full setup guide: [github.com/CoinCircuit/woo-commerce](https://github.com/CoinCircuit/woo-commerce) ## OpenCart For OpenCart 3.x stores. Shoppers pay in a CoinCircuit checkout that opens over your store's payment step, and orders move to the statuses you map in the extension settings. **[Download for OpenCart 3](https://github.com/CoinCircuit/open-cart3/releases/latest/download/coincircuit.ocmod.zip)** 1. In your store admin, go to **Extensions > Installer** and upload the zip. 2. Go to **Extensions > Extensions**, choose **Payments**, find **CoinCircuit**, and click Install. 3. Click Edit, enable it, and enter your API key and webhook secret. 4. Copy the webhook URL shown on the settings page and add it in the dashboard. Full setup guide: [github.com/CoinCircuit/open-cart3](https://github.com/CoinCircuit/open-cart3) ## Requirements - Store currency in NGN or USD - A public HTTPS store URL, so webhooks can reach your store - An API key and webhook secret from your dashboard --- # Fees | CoinCircuit Docs > What CoinCircuit charges per payment, payout, and refund. Source: https://coincircuit.io/docs/guides/fees/ Markdown: https://coincircuit.io/docs/guides/fees.md ## API reference - GET `/api/v1/payouts/fees`: [Get payout fees](https://coincircuit.io/api-reference/#tag/payouts/GET/api/v1/payouts/fees) - POST `/api/v1/payouts/cross-border/quote`: [Quote a cross-border payout](https://coincircuit.io/api-reference/#tag/payouts/POST/api/v1/payouts/cross-border/quote) CoinCircuit charges a small fee per transaction. No setup fees, no monthly fees, no hidden costs. Every fee is shown before you confirm, and each settlement records the gross amount, the fee, and the net that reached your balance. ## Accepting payments | Product | Fee | | :--- | :--- | | Payment links & invoices | 1% | | Deposit accounts | 0.5%, capped at 2 USDT | | x402 agent payments | Free | The deposit account fee applies to customer deposit accounts. Deposits into your own merchant account are free. ## Payouts Each payout charges a flat fee based on where the money goes. | Destination | Fee | | :--- | :--- | | Cross-border payouts (Kenya, Ghana) | 2 USD, debited from the funding stablecoin | | NGN bank transfer | ₦200 | | Tron (TRC-20) | 1.5 USDT | | Ethereum | 1.0 USDT | | BNB Smart Chain | 0.5 USDT | | Solana | 0.5 USDT | | Base | 0.5 USDT | ## Refunds | Action | Fee | | :--- | :--- | | Refund processing | 1.5 USDT | ## Swaps Swaps have no separate fee. The rate you lock in the quote is the rate you settle at. > Fees are returned by the API before you commit: `GET /api/v1/payouts/fees` for payout fees, `POST /api/v1/payouts/quote` for payouts in a different currency, and `GET /api/v1/swap/estimate` for swap rates. --- # Introduction | CoinCircuit Docs > Accept crypto payments, send payouts, and issue refunds through one API. Source: https://coincircuit.io/docs/guides/introduction/ Markdown: https://coincircuit.io/docs/guides/introduction.md **CoinCircuit** is crypto payment infrastructure. Accept payments online, in person, and from AI agents. Bill with invoices, send payouts, and issue refunds. ## What you can build - **Online payments.** Create a payment and redirect to a hosted checkout, or build your own UI on the API. - **In-store payments.** Share a payment page link or QR code, or take payments on a POS terminal at the counter. - **Invoices.** Send itemized invoices your customers pay in crypto. - **Agentic payments (x402).** Let AI agents and automated clients pay for your API per request, settled in stablecoins with gas covered. - **Payouts.** Withdraw your balance to a bank account or a crypto wallet. - **Refunds.** Refund a payment or an invoice, in full or in part. - **Deposit accounts.** Give each customer a reusable address to receive funds into their balance. - **Webhooks.** Get a signed event the moment a payment, payout, or refund changes state. ## Base URLs - **Production:** `https://api.coincircuit.io` - **Sandbox:** `https://sandbox-api.coincircuit.io` ## Start here Follow the Quick Start to take your first payment in a few minutes. To test without real funds first, set up the Sandbox. --- # Invoices | CoinCircuit Docs > Generate itemized invoices payable in crypto. Source: https://coincircuit.io/docs/guides/invoices/ Markdown: https://coincircuit.io/docs/guides/invoices.md ## API reference - POST `/api/v1/invoices`: [Create an invoice](https://coincircuit.io/api-reference/#tag/invoices/POST/api/v1/invoices) - GET `/api/v1/invoices/reference/{reference}`: [Retrieve an invoice](https://coincircuit.io/api-reference/#tag/invoices/GET/api/v1/invoices/reference/{reference}) - GET `/api/v1/invoices`: [List invoices](https://coincircuit.io/api-reference/#tag/invoices/GET/api/v1/invoices) An invoice bills a customer for itemized work. You list each line item with its quantity and price, CoinCircuit totals them, and the customer gets a page to pay in the crypto they choose. Invoices take partial payments, and a webhook tells you when one is settled in full. ![CoinCircuit invoice — line items, amount due, and pay link](https://coincircuit.io/images/features/invoices.webp) ## How it works 1. Create the invoice with `POST /api/v1/invoices`. 2. Share the invoice link with your customer. 3. Track payment with `GET /api/v1/invoices/reference/{reference}` or the `invoice.paid` webhook. 4. List all invoices with `GET /api/v1/invoices`. ## Request fields | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `items` | array | Yes | Line items. Each item requires `name`, `quantity`, and `unitPrice`; `description` and `unit` are optional. | | `currency` | string | Yes | `NGN` or `USD`. | | `description` | string | Yes | Shown to the customer on the invoice. | | `expiresAt` | string | Yes | ISO 8601 expiry date, up to 5 days from creation. | | `customer` | object | Yes | `email` and `firstName` are required. | | `reference` | string | No | Your invoice reference. Auto-generated if omitted. | | `asset` / `chain` | string | No | Lock the cryptocurrency and network for payment. | | `periodStart` / `periodEnd` | string | No | Billing period dates for recurring invoices. | | `successUrl` / `cancelUrl` | string | No | HTTPS redirect URLs after payment or cancellation. | | `metadata` | object | No | Key-value data returned in webhooks. | Add items line by line in the dashboard, each with a quantity and unit price: ![Invoice builder with line items](https://coincircuit.io/images/features/invoices-builder.webp) The customer sees a page with the amount due, line items, and a QR code: ![Invoice page with QR payment](https://coincircuit.io/images/features/invoices-pay.webp) ## Webhook events | Event | Sent when | | :--- | :--- | | `invoice.updated` | A partial payment is received. Compare `amountPaid` to `amount` to track progress. | | `invoice.paid` | The invoice is paid in full. Deliver the goods or service on this event. | | `invoice.expired` | The invoice expired before full payment. | ## Use cases - B2B billing and milestone payments - Client invoicing for services - Subscriptions and renewals > Invoices accept partial payments. Store your own reference in `metadata` to match payments to your records. --- # Limits | CoinCircuit Docs > Single-transaction and daily limits for payouts and swaps. Source: https://coincircuit.io/docs/guides/limits/ Markdown: https://coincircuit.io/docs/guides/limits.md Limits cap how much can move in a single transaction and per day. Every limit is checked before processing: a request over the limit is rejected with an error before any funds are held or charged. ## Single-transaction limits | Action | Maximum | | :--- | :--- | | Crypto payout | $50,000 | | NGN bank payout | ₦15,000,000 | | Swap from USDT or USDC | 30,000 | | Swap from NGN | ₦50,000,000 | To move more, split the amount into multiple transactions within your daily limit. ## Daily payout limits Your daily payout allowance depends on your verification tier. Identity (KYC) approval assigns KYC Verified; business (KYB) approval assigns KYB Verified. | Tier | Fiat payouts per day | Crypto payouts per day | | :--- | :--- | :--- | | Unverified | Not available | Not available | | KYC Verified | ₦5,000,000 | $10,000 | | KYB Verified | ₦10,000,000 | $100,000 | Need higher limits? Contact [support@coincircuit.io](mailto:support@coincircuit.io). Cross-border payouts count toward the fiat daily limit at their NGN equivalent. ## Cross-border payout limits Each cross-border payout must fall within the corridor's range, in the currency the recipient receives. | Corridor | Minimum | Maximum | | :--- | :--- | :--- | | Kenya (KES) | 20 | 250,000 | | Ghana (GHS) | 20 | 15,000 | > Limits apply per merchant account. To raise yours, contact [support@coincircuit.io](mailto:support@coincircuit.io). Every transaction is screened under our [AML policy](https://coincircuit.io/aml). --- # Marketplace Vendor Payouts | CoinCircuit Docs > Collect crypto from buyers and pay vendors out in crypto. Source: https://coincircuit.io/docs/guides/marketplace-settlement/ Markdown: https://coincircuit.io/docs/guides/marketplace-settlement.md Tags: Payments, Payouts, Balance Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me integrate CoinCircuit into my existing marketplace for buyer payments and vendor payouts. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_endpoint` with method `post` and path `/api/v1/payments` in the CoinCircuit MCP for the checkout session creation schema. - Call `get_endpoint` with method `get` and path `/api/v1/balance` for the balance response schema. - Call `get_endpoint` with method `post` and path `/api/v1/payouts` for the payout creation schema. - Call `get_endpoint` with method `post` and path `/api/v1/recipients` for the recipient creation schema. - Call `get_endpoint` with method `get` and path `/api/v1/rates/convert` for the exchange rate schema. - Call `get_schema` with name `PaymentCompletedWebhookDto` for the payment.completed webhook payload. - Call `get_schema` with name `PayoutSuccessWebhookDto` for the payout.success webhook payload. - Call `get_schema` with name `PayoutFailedWebhookDto` for the payout.failed webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have a marketplace that collects payment from buyers, takes a platform fee, and distributes the rest to vendors. I'm integrating CoinCircuit for crypto payments. CoinCircuit does not natively split payments, so the architecture is: ``` Buyer pays crypto -> CoinCircuit collects -> Merchant balance grows -> I pay out to vendors ``` **Important:** Vendor distribution uses crypto payouts (USDT to wallet addresses). Fiat payouts go only to the merchant's own bank account, not to third-party vendors. ## What I Need You to Implement ### 1. Collect payment from buyer **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `example` in the CoinCircuit MCP for a ready-to-use sample request.)* Create a checkout session for the full order amount. Store the vendor split in `metadata`: ```json { "title": "Order #ORD-123", "description": "Marketplace order with 2 vendors", "amount": "150.00", "currency": "USD", "customer": { "email": "buyer@example.com" }, "metadata": { "orderId": "ORD-123", "platformFee": "15.00", "vendors": [ { "vendorId": "v1", "amount": "90.00", "cryptoAddressId": "addr_v1_uuid" }, { "vendorId": "v2", "amount": "45.00", "cryptoAddressId": "addr_v2_uuid" } ] }, "successUrl": "https://marketplace.com/order/ORD-123/success", "cancelUrl": "https://marketplace.com/cart" } ``` Response gives you `data.reference` for the checkout SDK and `data.url` for the hosted page. ### 2. On payment.completed, queue vendor payouts When the `payment.completed` webhook fires: *(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP to see every field in the webhook payload, including settlements and transaction details.)* 1. Verify the signature (`x-coincircuit-signature`, HMAC-SHA256) 2. Check idempotency (`x-coincircuit-delivery-id`) 3. Parse vendor split from `data.session.metadata.vendors` 4. Lock the conversion rate from `data.session.payment.conversionRate` and `data.session.settlements` 5. Deduct your platform fee 6. Queue crypto payouts for each vendor ### 3. Check balance before paying vendors **Endpoint:** `GET /api/v1/balance?currency=USDT` *(Call `get_endpoint` with method `get`, path `/api/v1/balance` in the CoinCircuit MCP for the full response schema.)* Verify `availableBalance` covers all vendor payouts plus fees. The response includes `totalBalance`, `availableBalance`, and `pendingBalance`. ### 4. Pay vendors via crypto payouts **Endpoint:** `POST /api/v1/payouts` *(Call `get_endpoint` with method `post`, path `/api/v1/payouts`, section `request` in the CoinCircuit MCP for the exact request body with all field validations.)* For each vendor: ```json { "method": "crypto", "currency": "USDT", "amount": "90.00", "recipientId": "addr_v1_uuid", "narration": "Vendor payout - Order ORD-123", "reference": "PAYOUT-ORD123-V1" } ``` Each payout returns with `status: "pending"`. The response includes `fee`, `total` (amount + fee), and `conversion` details if cross-currency. ### 5. Track vendor payout status *(Call `get_schema` with name `PayoutSuccessWebhookDto` and `PayoutFailedWebhookDto` in the CoinCircuit MCP for the full webhook payloads.)* **Webhook events:** - `payout.success` - funds delivered. `data.payout.txHash` and `data.payout.completedAt` confirm delivery. - `payout.failed` - payout failed. `data.payout.failureReason` explains why. Funds return to your balance. Retry or escalate. ### 6. Vendor onboarding Each vendor saves their crypto wallet address: **Endpoint:** `POST /api/v1/recipients` *(Call `get_endpoint` with method `post`, path `/api/v1/recipients` in the CoinCircuit MCP for the full request/response schema.)* ```json { "type": "crypto_address", "label": "Vendor Alice - Tron wallet", "isDefault": true, "details": { "chain": "tron", "address": "TF6yMCJqFcT6wFFutxVmRocKgJFD5imKUT" } } ``` Supported chains: `"bsc"`, `"tron"`, `"solana"`, `"base"`, `"ethereum"`. The response `data.id` is the UUID you use as `recipientId` in payouts. If a matching recipient already exists, the existing one is returned instead of a duplicate. ### 7. Exchange rates for display **Endpoint:** `GET /api/v1/rates/convert?from=USDT&to=NGN` *(Call `get_endpoint` with method `get`, path `/api/v1/rates/convert` in the CoinCircuit MCP for the full response schema. You can also call `get_all_conversion_rates` in the CoinCircuit MCP to see all live rates.)* Returns: ```json { "success": true, "data": { "rate": 1462.1, "from": "USDT", "to": "NGN", "timestamp": "2025-01-15T10:30:00.000Z" } } ``` Both `from` and `to` must be uppercase. Supports fiat (NGN, USD, EUR, GBP) and crypto (BTC, ETH, USDT, USDC, BNB, SOL, XRP). Use this to show vendors their expected payout in local currency. ## Constraints - Store vendor split data in payment `metadata` so your webhook handler can process it - Check `availableBalance` before creating vendor payouts - Use unique `reference` values per payout. Duplicates are rejected. - Exchange rates fluctuate. Lock amounts at payment time using the session's conversion rate from `data.session.settlements.gross.conversionRate`. - Fiat payouts go only to the merchant's own bank account. Use crypto payouts for vendor distribution. - Payout `amount` is a string. Balance values are also strings. --- # MCP Integration | CoinCircuit Docs > Connect AI IDEs to CoinCircuit through MCP. Source: https://coincircuit.io/docs/guides/mcp/ Markdown: https://coincircuit.io/docs/guides/mcp.md CoinCircuit provides a **Model Context Protocol (MCP)** server so AI-powered IDEs like Cursor, Windsurf, and Claude Desktop can read the docs and call the API directly. ## Connection **MCP URL:** `https://mcp.coincircuit.io` Generate an MCP access key in the dashboard under **Developer > MCP Access Keys**, then add it to your client config: ```json { "mcpServers": { "coincircuit": { "url": "https://mcp.coincircuit.io", "headers": { "x-mcp-key": "YOUR_MCP_KEY" } } } } ``` ## Authentication Browsing documentation and discovering the API schema work without authentication. A key is only required to execute tools such as creating payments or listing transactions. --- # Migrate from Cryptomus | CoinCircuit Docs > Move from Cryptomus to CoinCircuit: swap request signing for an API key, update webhook verification, and map every field. Source: https://coincircuit.io/docs/guides/migrate-from-cryptomus/ Markdown: https://coincircuit.io/docs/guides/migrate-from-cryptomus.md CoinCircuit and Cryptomus solve the same problem. You create a payment, your customer sends crypto to an address, and your server gets a callback when it settles. The concepts line up almost one to one. The real work is in two places: **request authentication** and **webhook verification**. Cryptomus signs every request body with MD5; CoinCircuit uses a static API key header and signs webhooks with HMAC-SHA256. Both changes delete code rather than add it. ## Concept mapping | Cryptomus | CoinCircuit | Notes | | :--- | :--- | :--- | | Payment | Payment (checkout session) | One charge, one address, one webhook. | | `uuid` / `order_id` | `reference` / `metadata` | `reference` is CoinCircuit's handle; put your own ID in `metadata`. | | Static wallet | Deposit account | A reusable address that credits your balance. | | Recurring payment | Invoice + webhooks | Rebuild the schedule on your side; bill with invoices. | | Callback (`url_callback`) | Webhook (`webhookUrl`) | Same delivery model, different signing. | | `sign` field in the body | `x-coincircuit-signature` header | Moves out of the payload and into a header. | | Payment API key + Payout API key | One API key | CoinCircuit does not split keys by operation. | | Merchant balance | Balance | Per-asset balance credited after each payment. | | Payout | Payout | Save a recipient once, then pay out to it. | --- ## Step 1: Replace request signing with an API key This is the biggest change, and it removes code. #### Cryptomus (before) Every request carried a `merchant` header and a `sign` header. The signature was an MD5 of the base64-encoded JSON body concatenated with your API key, recomputed per request. ```js const body = JSON.stringify(payload); const sign = crypto .createHash('md5') .update(Buffer.from(body).toString('base64') + API_KEY) .digest('hex'); await fetch('https://api.cryptomus.com/v1/payment', { method: 'POST', headers: { merchant: MERCHANT_UUID, sign, 'Content-Type': 'application/json', }, body, }); ``` #### CoinCircuit (after) One static header. Delete the signing helper. ```http POST https://api.coincircuit.io/api/v1/payments x-api-key: sk_live_your_key Content-Type: application/json ``` ```diff - merchant: 8b03432e-385b-4670-8d06-064591096795 - sign: 8b03432e385b46708d06064591096795 + x-api-key: sk_live_your_coincircuit_key ``` Change your base URL: ```diff - https://api.cryptomus.com/v1 + https://api.coincircuit.io/api/v1 ``` Generate your key in the dashboard under **Developers > API keys**. Keep it server-side. --- ## Step 2: Create payments #### Cryptomus (before) ```http POST /v1/payment ``` ```json { "amount": "100", "currency": "USD", "order_id": "order_123", "url_callback": "https://your-site.com/webhook", "url_return": "https://your-site.com/cart", "url_success": "https://your-site.com/success", "lifetime": 3600 } ``` #### CoinCircuit (after) ```http POST https://api.coincircuit.io/api/v1/payments x-api-key: sk_live_your_key Content-Type: application/json ``` ```json { "title": "Order #order_123", "description": "T-shirt", "amount": "100.00", "currency": "USD", "customer": { "email": "customer@example.com" }, "webhookUrl": "https://your-site.com/webhook", "successUrl": "https://your-site.com/success", "cancelUrl": "https://your-site.com/cart", "metadata": { "orderId": "order_123" } } ``` The response is wrapped in the standard `{ success, message, data }` envelope. Redirect the customer to `data.url` for the hosted checkout, and store `data.reference` against your order. ### Field mapping | Cryptomus field | CoinCircuit field | Notes | | :--- | :--- | :--- | | `amount` | `amount` | Send as a string, e.g. `"100.00"`. | | `currency` | `currency` | `NGN` or `USD`. | | `to_currency` | `asset` | Optional. Omit to let the customer choose the asset. | | `network` | `chain` | Optional. Omit to let the customer choose the network. | | `order_id` | `metadata` | Any key-value data; it comes back on every webhook. | | `url_callback` | `webhookUrl` | Per-payment webhook URL. | | `url_success` | `successUrl` | Redirect after a successful payment. | | `url_return` | `cancelUrl` | Redirect when the customer backs out. | | `is_payment_multiple` | — | CoinCircuit accepts additional payments while the session is open. | | `lifetime` | — | Expiry is set by CoinCircuit and returned as `data.expiresAt`. | | `subtract` | `feePaidBy` | `"customer"` or `"merchant"`; defaults to your dashboard setting. | > Cryptomus returns both `address` and `url`. If you rendered your own payment UI from `address`, you can keep doing that: set `asset` and `chain` on the payment and read the deposit address from the response instead of redirecting. --- ## Step 3: Replace recurring payments with invoices Cryptomus had a dedicated recurring endpoint. CoinCircuit does not bill on a schedule for you: keep the schedule in your system and issue an invoice each cycle. ```http POST https://api.coincircuit.io/api/v1/invoices x-api-key: sk_live_your_key Content-Type: application/json ``` ```json { "description": "Pro plan for July", "currency": "USD", "customer": { "email": "client@example.com", "firstName": "Ada" }, "reference": "sub_2026_07", "items": [ { "name": "Pro plan", "quantity": 1, "unitPrice": 49 } ] } ``` Invoices are line-item based, so each plan or add-on becomes an `items` entry. Share the hosted invoice link and fulfil on the paid webhook. Your own cron decides when the next invoice goes out. --- ## Step 4: Migrate webhooks Both platforms POST JSON to your callback URL. The difference is **where the signature lives and how it is computed**. #### Cryptomus signature (before) The signature arrived **inside the payload** as a `sign` field. You removed it, base64-encoded the remaining JSON, and MD5'd it with your API key. ```js const { sign, ...payload } = req.body; const expected = crypto .createHash('md5') .update(Buffer.from(JSON.stringify(payload)).toString('base64') + API_KEY) .digest('hex'); const isValid = expected === sign; ``` #### CoinCircuit signature (after) The signature arrives in the **`x-coincircuit-signature` header**, formatted `v1=`. It is an HMAC-SHA256 over `.`, where the timestamp comes from the `x-coincircuit-timestamp` header. ```js const crypto = require('crypto'); function verifyWebhook(rawBody, timestamp, header, secret) { // Reject anything older than 5 minutes to block replays. const age = Math.floor(Date.now() / 1000) - Number(timestamp); if (!timestamp || age < 0 || age > 300) return false; const expected = crypto .createHmac('sha256', secret) .update(`${timestamp}.${rawBody}`) // raw bytes, not parsed JSON .digest('hex'); const received = String(header).replace(/^v1=/, ''); const a = Buffer.from(expected, 'hex'); const b = Buffer.from(received, 'hex'); return a.length === b.length && crypto.timingSafeEqual(a, b); } // Express app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => { const ok = verifyWebhook( req.body, req.headers['x-coincircuit-timestamp'], req.headers['x-coincircuit-signature'], process.env.WEBHOOK_SECRET, ); if (!ok) return res.status(401).send('Invalid signature'); const { event, data } = JSON.parse(req.body.toString('utf8')); // handle event res.sendStatus(200); }); ``` ### Status mapping Cryptomus reported state through `payment_status`. CoinCircuit sends a named `event` instead. | Cryptomus status | CoinCircuit event | Trigger | | :--- | :--- | :--- | | `process` | — | No pre-deposit event; the session simply stays open. | | `check` / `confirm_check` | `transaction.received` | Deposit seen on-chain, awaiting confirmations. | | — | `transaction.confirmed` | Transaction confirmed on the blockchain. | | `paid` | `payment.completed` | Settled in full. Fulfil the order here. | | `paid_over` | `payment.completed` | Overpayment; compare `amountReceived` against the amount due. | | `wrong_amount` / `wrong_amount_waiting` | `payment.partial` | Underpaid; the session stays open for the balance. | | `fail` / `cancel` / `system_fail` | `payment.expired` | Session closed without full payment. | | `refund_paid` | `refund.success` | Refund confirmed on-chain. | | `refund_fail` | `refund.failed` | Refund could not be completed. | Fulfil on `payment.completed` (was `paid`). Your `order_id` lives in `metadata` and is returned on every event. --- ## Step 5: Migrate payouts #### Cryptomus (before) Payouts used a **separate payout API key** and took the destination address inline on every call. ```http POST /v1/payout ``` ```json { "amount": "500", "currency": "USDT", "network": "tron", "order_id": "payout_1", "address": "TRecipientAddress", "is_subtract": true } ``` #### CoinCircuit (after) Same API key as everything else. Save the destination once as a recipient, then reference it by ID, so an address is verified and reusable instead of re-sent each time. ```http POST https://api.coincircuit.io/api/v1/recipients x-api-key: sk_live_your_key Content-Type: application/json { "type": "crypto_address", "label": "Vendor A", "details": { "chain": "tron", "address": "TRecipientAddress" } } ``` Check the cost before sending: ```http GET https://api.coincircuit.io/api/v1/payouts/fees x-api-key: sk_live_your_key ``` Then create the payout: ```http POST https://api.coincircuit.io/api/v1/payouts x-api-key: sk_live_your_key Content-Type: application/json { "method": "crypto", "recipientId": "recipient-id-from-above", "amount": "500.00", "currency": "USDT", "reference": "payout_1" } ``` Listen for `payout.success` or `payout.failed` to confirm the result. --- ## Step 6: Check payment status #### Cryptomus (before) ```http POST /v1/payment/info ``` ```json { "uuid": "8b03432e-385b-4670-8d06-064591096795" } ``` #### CoinCircuit (after) A plain GET by the reference you stored when creating the payment. ```http GET https://api.coincircuit.io/api/v1/payments/reference/{reference} x-api-key: sk_live_your_key ``` To list payments: ```http GET https://api.coincircuit.io/api/v1/payments?page=1&size=20 ``` > Treat status polling as a fallback. Webhooks are the reliable path; poll only when you have missed a delivery. --- ## Step 7: Test in the sandbox CoinCircuit has a full sandbox on testnet. Point your integration at the sandbox base URL with a test key before going live. ```diff - https://api.coincircuit.io/api/v1 + https://sandbox-api.coincircuit.io/api/v1 ``` Use the **Simulate payment** button on the sandbox checkout page to trigger outcomes (full, partial, overpayment) without moving real funds. See the [Sandbox Environment](https://coincircuit.io/guides/sandbox) guide for faucet links and testnet details. --- # Migrate from NOWPayments | CoinCircuit Docs > Move from NOWPayments to CoinCircuit: endpoint mapping, webhook re-signing, and a step-by-step checklist. Source: https://coincircuit.io/docs/guides/migrate-from-nowpayments/ Markdown: https://coincircuit.io/docs/guides/migrate-from-nowpayments.md CoinCircuit and NOWPayments share the same core model — you create a payment, your customer pays a crypto address, and you receive a signed webhook when it settles. The concepts map directly, so migration is mostly a find-and-replace of endpoints, field names, and the signing algorithm. ## Concept mapping | NOWPayments | CoinCircuit | Notes | | :--- | :--- | :--- | | Payment | Payment (checkout session) | Same idea: one charge, one address, one webhook. | | Invoice | Invoice | Itemized, multi-line billing with a pay link. | | IPN callback | Webhook | Same delivery model; different signing algorithm. | | IPN secret key | Webhook secret | Used to verify the signature on each event. | | `x-nowpayments-sig` header | `x-coincircuit-signature` header | Header name changes; see signing below. | | Primary balance | Balance | Per-asset balance credited after each payment. | | Mass payouts | Payouts | Send crypto to any wallet in a single API call. | | Custodial recurring payments | — | Use invoices + webhooks to rebuild recurring billing. | --- ## Step 1 — Create payments #### NOWPayments flow (before) NOWPayments required two pre-flight calls — check the minimum amount, get an estimated price — before creating a payment. ```http GET /v1/min-amount?currency_from=btc¤cy_to=eth GET /v1/estimate?amount=100¤cy_from=usd¤cy_to=btc POST /v1/payment ``` ```json { "price_amount": 100, "price_currency": "usd", "pay_currency": "btc", "ipn_callback_url": "https://your-site.com/webhook", "order_id": "order_123", "order_description": "T-shirt" } ``` #### CoinCircuit flow (after) One call. CoinCircuit prices the payment and returns the crypto amount to collect in the payment response. You set the `asset` and `chain`, or omit them to let the customer pick at checkout. ```http POST https://api.coincircuit.io/api/v1/payments x-api-key: sk_live_your_key Content-Type: application/json ``` ```json { "title": "T-shirt", "description": "Order #order_123", "amount": "100.00", "currency": "USD", "customer": { "email": "customer@example.com" }, "webhookUrl": "https://your-site.com/webhook", "metadata": { "orderId": "order_123" } } ``` The response includes `checkoutUrl` — redirect the customer there. CoinCircuit locks the crypto rate for the asset and chain, whether you set them or the customer picks at checkout. ### Field mapping | NOWPayments field | CoinCircuit field | Notes | | :--- | :--- | :--- | | `price_amount` | `amount` | Pass as a string, e.g. `"100.00"`. | | `price_currency` | `currency` | `NGN` or `USD`. | | `pay_currency` | `asset` | Optional. Omit to let the customer choose. | | `ipn_callback_url` | `webhookUrl` | Per-payment webhook URL. | | `order_id` / `order_description` | `metadata` | Store any key-value data you need in webhooks. | | `success_url` | `successUrl` | Redirect after successful payment. | | `cancel_url` | `cancelUrl` | Redirect after cancellation. | --- ## Step 2 — Replace invoices #### NOWPayments (before) ```http POST /v1/invoice ``` ```json { "price_amount": 500, "price_currency": "usd", "order_id": "inv_001", "order_description": "Consulting — June", "success_url": "https://your-site.com/thank-you", "ipn_callback_url": "https://your-site.com/webhook" } ``` #### CoinCircuit (after) ```http POST https://api.coincircuit.io/api/v1/invoices x-api-key: sk_live_your_key Content-Type: application/json ``` ```json { "description": "Consulting — June", "currency": "USD", "expiresAt": "2026-08-01T00:00:00Z", "customer": { "email": "client@example.com", "firstName": "Ada" }, "reference": "inv_001", "successUrl": "https://your-site.com/thank-you", "items": [ { "name": "Consulting", "quantity": 10, "unitPrice": 50 } ] } ``` CoinCircuit invoices are line-item based. If NOWPayments was your invoicing layer, map each product or service into an `items` entry. The `reference` field replaces `order_id`. --- ## Step 3 — Migrate webhooks Both platforms POST a JSON body to your callback URL when a payment status changes. The main difference is the **signature algorithm**. #### NOWPayments signature (before) 1. Sort the request body by keys recursively. 2. Serialize with `JSON.stringify(sortedBody)`. 3. HMAC-SHA512 the string with your IPN secret. 4. Compare against the `x-nowpayments-sig` header. ```js const hmac = crypto.createHmac('sha512', ipnSecret); hmac.update(JSON.stringify(sortObject(body))); const expected = hmac.digest('hex'); const isValid = expected === req.headers['x-nowpayments-sig']; ``` #### CoinCircuit signature (after) CoinCircuit signs the timestamped payload with HMAC-SHA256 and sends the result in the `x-coincircuit-signature` header as `v1=`, alongside an `x-coincircuit-timestamp` header. Rebuild the signed string as `timestamp.payload`, recompute the HMAC, strip the `v1=` prefix, and compare in constant time. ```js const crypto = require('crypto'); function verifyWebhookSignature(payload, signature, secret, timestamp) { try { const signedPayload = timestamp ? `${timestamp}.${payload}` : payload; const expectedSignature = crypto.createHmac('sha256', secret).update(signedPayload, 'utf8').digest('hex'); // The signature header is "v1="; strip the version prefix before comparing. const received = signature.replace(/^v1=/, ''); return crypto.timingSafeEqual(Buffer.from(received, 'hex'), Buffer.from(expectedSignature, 'hex')); } catch (_) { return false; } } // Express example app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => { const payload = req.body.toString('utf8'); const signature = req.headers['x-coincircuit-signature']; const timestamp = req.headers['x-coincircuit-timestamp']; if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET, timestamp)) { return res.status(401).send('Invalid signature'); } const event = JSON.parse(payload); // handle event res.sendStatus(200); }); ``` > Use `express.raw()` (or equivalent) so you verify the exact bytes CoinCircuit signed, before any JSON parsing. ### Webhook event mapping | NOWPayments status | CoinCircuit event | Trigger | | :--- | :--- | :--- | | `waiting` | — | CoinCircuit omits pre-deposit waiting events. | | `confirming` | `transaction.received` | Deposit detected on-chain, awaiting confirmation. | | `confirmed` | `transaction.confirmed` | Transaction confirmed on the blockchain. | | `finished` | `payment.completed` | Payment settled in full — fulfil the order on this. | | `partially_paid` | `payment.partial` | Partial deposit received. | | `failed` / `expired` | `payment.expired` | Session expired or payment could not be completed. | | `refunded` | `refund.success` | Refund confirmed on-chain. | Fulfil orders on `payment.completed` (was `finished` in NOWPayments). Store your internal order ID in `metadata` when creating the payment — it comes back on every event. --- ## Step 4 — Migrate payouts #### NOWPayments mass payout (before) NOWPayments batched payouts in a single `/payout` call with an array of withdrawals and a separate IPN secret. #### CoinCircuit payout (after) Save the recipient once, then initiate per payout. Check fees before sending. ```http POST https://api.coincircuit.io/api/v1/recipients x-api-key: sk_live_your_key Content-Type: application/json { "type": "crypto_address", "label": "Vendor A", "details": { "chain": "base", "address": "0xRecipientAddress" } } ``` ```http GET https://api.coincircuit.io/api/v1/payouts/fees x-api-key: sk_live_your_key ``` ```http POST https://api.coincircuit.io/api/v1/payouts x-api-key: sk_live_your_key Content-Type: application/json { "method": "crypto", "currency": "USDC", "amount": "500.00", "recipientId": "recipient-id-from-step-above" } ``` Listen for `payout.success` or `payout.failed` webhooks to confirm the result. --- ## Step 5 — Check payment status #### NOWPayments (before) ```http GET /v1/payment/{paymentId} ``` #### CoinCircuit (after) ```http GET https://api.coincircuit.io/api/v1/payments/reference/{reference} x-api-key: sk_live_your_key ``` Retrieve by the `reference` returned when you created the payment. To list all payments: ```http GET https://api.coincircuit.io/api/v1/payments?page=1&size=20 ``` --- ## Step 6 — Test in the sandbox CoinCircuit has a full sandbox environment on testnet. Point your integration at the sandbox base URL with test API keys before going live. ```diff - https://api.coincircuit.io/api/v1 + https://sandbox-api.coincircuit.io/api/v1 ``` Use the **Simulate payment** button on the sandbox checkout page to trigger payment outcomes (full, partial, overpayment, AML failure) without moving real funds. See the [Sandbox Environment](https://coincircuit.io/guides/sandbox) guide for faucet links and testnet details. --- # Migrate from Triple-A | CoinCircuit Docs > Move from Triple-A to CoinCircuit: swap OAuth2 for an API key, update webhook signing, and map every field. Source: https://coincircuit.io/docs/guides/migrate-from-triplea/ Markdown: https://coincircuit.io/docs/guides/migrate-from-triplea.md Triple-A and CoinCircuit are both licensed crypto payment platforms — you create a payment, the customer sends crypto to an address, and your server receives a notification when it settles. The integration model is similar, but the two platforms differ significantly in **authentication** and **webhook signing**. Triple-A uses OAuth2 client credentials for every API call; CoinCircuit uses a single static API key. Triple-A signs notifications with a per-payment secret; CoinCircuit signs with a global webhook secret using HMAC-SHA256 on the raw request body. ## Concept mapping | Triple-A | CoinCircuit | Notes | | :--- | :--- | :--- | | OAuth2 Bearer token | `x-api-key` header | One static key replaces the token flow entirely. | | `client_id` + `client_secret` | API key | Generate once in the dashboard under **Developer > API Keys**. | | `merchant_key` | — | CoinCircuit keys are already scoped to your account. | | Payment (`type: triplea`) | Payment (checkout session) | Redirect the customer to `checkoutUrl`. | | Invoice (`type: invoice`) | Invoice | Itemised billing with a hosted pay link. | | Widget (`type: widget`) | Checkout session | CoinCircuit's hosted checkout embeds the same way. | | `notify_url` | `webhookUrl` | Per-payment webhook URL. | | `notify_secret` | Webhook secret | Set once in the dashboard; CoinCircuit signs all events with it. | | `payment_reference` | `reference` | Unique ID returned when you create the payment. | | `order_id` | `metadata.orderId` | Store your internal ID in `metadata` — it comes back on every event. | | `webhook_data` | `metadata` | Any extra key-value data passed through to webhooks. | | Payment tier (`good` / `hold` / `invalid`) | Webhook events | See event mapping in Step 4. | | `/api/v2/payout/withdraw/...` | `POST /api/v1/payouts` | Save a recipient once, then pay out to it. | | `sandbox: true` in request body | Sandbox base URL | Use `https://sandbox-api.coincircuit.io` with test keys. | --- ## Step 1 — Replace OAuth2 with an API key Triple-A requires a token exchange before every session. You POST your `client_id` and `client_secret` to get a Bearer token, then send it on every subsequent request. **Triple-A** ```http POST https://api.triple-a.io/api/v2/oauth/token Content-Type: application/x-www-form-urlencoded client_id=oacid-*****&client_secret=Qi42***&grant_type=client_credentials ``` ```json { "access_token": "1ba8***", "token_type": "bearer", "expires_in": 315359999 } ``` Every subsequent request then sends `Authorization: Bearer 1ba8***`. **CoinCircuit** Delete the token exchange entirely. Every request sends one static header: ```http x-api-key: sk_live_your_key ``` Generate your key in the dashboard under **Developer > API Keys**. Test keys work against `https://sandbox-api.coincircuit.io`; live keys work against `https://api.coincircuit.io`. --- ## Step 2 — Create payments Triple-A has three payment types in one endpoint: `triplea` (hosted redirect), `widget` (embedded), and `invoice` (invoice link). The `merchant_key` selects which merchant account receives funds, and `notify_secret` signs each notification individually. **Triple-A** ```http POST https://api.triple-a.io/api/v2/payment Authorization: Bearer Content-Type: application/json { "type": "triplea", "merchant_key": "mkey-ckfhqahxy04g6e4qs6t3f00nl", "order_currency": "USD", "order_amount": 10, "order_id": "TSGA267KL", "notify_url": "https://your-site.com/webhook", "notify_secret": "Cf9mx4nAvRuy5vwBY2FCtaKr", "payer_email": "alice@example.com", "success_url": "https://your-site.com/success", "cancel_url": "https://your-site.com/cancel", "webhook_data": { "order_id": "TSGA267KL" } } ``` The response includes `hosted_url` — redirect the customer there. **CoinCircuit** ```http POST https://api.coincircuit.io/api/v1/payments x-api-key: sk_live_your_key Content-Type: application/json { "title": "Order TSGA267KL", "description": "Your order description", "amount": "10.00", "currency": "USD", "customer": { "email": "alice@example.com" }, "webhookUrl": "https://your-site.com/webhook", "successUrl": "https://your-site.com/success", "cancelUrl": "https://your-site.com/cancel", "metadata": { "orderId": "TSGA267KL" } } ``` The response includes `checkoutUrl` — redirect the customer there. CoinCircuit handles exchange rate locking and crypto selection internally. **Field mapping** | Triple-A field | CoinCircuit field | Notes | | :--- | :--- | :--- | | `type` | — | Not needed; CoinCircuit has one payment type. | | `merchant_key` | — | Your API key already scopes to your account. | | `order_currency` | `currency` | `NGN` or `USD`. | | `order_amount` | `amount` | Pass as a string, e.g. `"10.00"`. | | `order_id` | `metadata.orderId` | Stored in `metadata`; returned on every webhook. | | `notify_url` | `webhookUrl` | Per-payment webhook URL. | | `notify_secret` | Webhook secret | Set once in the dashboard; no longer per-payment. | | `payer_email` | `customer.email` | Required. | | `payer_name` | `customer.firstName` + `customer.lastName` | Split into two fields. | | `payer_phone` | `customer.phone` | Optional. | | `success_url` | `successUrl` | Redirect on successful payment. | | `cancel_url` | `cancelUrl` | Redirect on cancellation. | | `webhook_data` | `metadata` | Any key-value data echoed back in webhooks. | --- ## Step 3 — Replace invoices Triple-A's invoice type (`type: invoice`) emails the customer a hosted invoice URL. CoinCircuit invoices are line-item based. **Triple-A** ```json { "type": "invoice", "merchant_key": "mkey-ckfhqahxy04g6e4qs6t3f00nl", "order_currency": "USD", "order_amount": 100, "order_id": "INV-001", "invoice_desc": "Consulting services — June", "notify_payer": true, "payer_email": "client@example.com", "payer_name": "Alice Tan" } ``` **CoinCircuit** Map `invoice_desc` to `description` and break the total into `items`. The `reference` field replaces `order_id`. ```http POST https://api.coincircuit.io/api/v1/invoices x-api-key: sk_live_your_key Content-Type: application/json { "description": "Consulting services — June", "currency": "USD", "expiresAt": "2026-08-01T00:00:00Z", "reference": "INV-001", "customer": { "email": "client@example.com", "firstName": "Alice" }, "items": [ { "name": "Consulting services — June", "quantity": 1, "unitPrice": 100 } ] } ``` The response includes `invoiceUrl` — share it with your customer or embed it in your own email. --- ## Step 4 — Migrate webhooks Triple-A POSTs to your `notify_url` when a payment changes tier. Each payment carries its own `notify_secret`; if omitted, Triple-A auto-generates one and returns it in the create-payment response. **Triple-A notification payload** ```json { "event": "payment", "merchant_key": "mkey-ckfhqahxy04g6e4qs6t3f00nl", "payment_reference": "SDF-453672-PMT", "status": "good", "payment_tier": "good", "order_currency": "USD", "payment_amount": 10, "webhook_data": { "order_id": "TSGA267KL" } } ``` **CoinCircuit webhook handler** CoinCircuit uses a single global webhook secret and signs every event with HMAC-SHA256 on the raw request body, sending the result in the `x-coincircuit-signature` header. ```js const crypto = require('crypto'); app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => { const sig = req.headers['x-coincircuit-signature']; const expected = crypto .createHmac('sha256', process.env.WEBHOOK_SECRET) .update(req.body) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) { return res.status(401).send('Invalid signature'); } const event = JSON.parse(req.body); res.sendStatus(200); }); ``` > Use `express.raw()` so you verify the exact bytes CoinCircuit signed, before any JSON parsing. **Key signing differences** | Triple-A | CoinCircuit | | :--- | :--- | | Per-payment `notify_secret` | Single global webhook secret in the dashboard | | No documented signature header | `x-coincircuit-signature` (HMAC-SHA256 hex) | | `notify_url` per payment | `webhookUrl` per payment, or global URL in dashboard | | `webhook_data` echoed in body | `metadata` echoed in every event | ## Payment tier mapping | Triple-A `status` / `payment_tier` | CoinCircuit event | Meaning | | :--- | :--- | :--- | | `none` | — | No funds received yet; CoinCircuit omits pre-deposit events. | | `short` | `transaction.received` | Funds detected on-chain, not yet confirmed. | | `hold` | `transaction.confirmed` | Transaction confirmed on the blockchain. | | `good` | `payment.completed` | Payment settled in full — fulfil the order on this event. | | `invalid` | `payment.expired` | Payment expired or could not be completed. | | — | `payment.partial` | Partial deposit received. | Fulfil orders on `payment.completed` (was `good` in Triple-A). Your `order_id` from `webhook_data` is now in `metadata` and comes back on every event. --- ## Step 5 — Migrate payouts Triple-A emails the recipient a payout form to collect their wallet address. CoinCircuit saves the recipient once and pays out directly. **Triple-A** ```http POST https://api.triple-a.io/api/v2/payout/withdraw/local/crypto Authorization: Bearer Content-Type: application/json { "merchant_key": "mkey-ck9e0srok0000zumg7vx3hpkh", "email": "alice@example.com", "withdraw_currency": "USDT", "withdraw_amount": 50, "order_id": "PAYOUT-001", "notify_url": "https://your-site.com/webhook" } ``` Check balance first with `GET /api/v2/payout/balances`. Track status with `GET /api/v2/payout/withdraw/{payout_reference}`. Payout statuses: `new` → `confirm` → `done` (or `cancel`). **CoinCircuit** ```http POST https://api.coincircuit.io/api/v1/crypto-addresses x-api-key: sk_live_your_key Content-Type: application/json { "address": "0xRecipientAddress", "chain": "base", "asset": "USDT", "label": "Alice" } ``` ```http GET https://api.coincircuit.io/api/v1/payouts/fees?asset=USDT&chain=base&amount=50 ``` ```http POST https://api.coincircuit.io/api/v1/payouts x-api-key: sk_live_your_key Content-Type: application/json { "asset": "USDT", "chain": "base", "amount": "50.00", "recipientId": "crypto-address-id-from-above" } ``` Listen for `payout.success` or `payout.failed` webhooks. Track status with `GET /api/v1/payouts/{id}`. --- ## Step 6 — Check payment status **Triple-A:** `GET https://api.triple-a.io/api/v2/payment/{payment_reference}` with `Authorization: Bearer `. **CoinCircuit:** ```http GET https://api.coincircuit.io/api/v1/payments/reference/{reference} x-api-key: sk_live_your_key ``` The `reference` is returned when you create the payment. To list all payments: ```http GET https://api.coincircuit.io/api/v1/payments?page=1&size=20 x-api-key: sk_live_your_key ``` --- ## Step 7 — Test in the sandbox Triple-A activates test mode with a `sandbox: true` flag in the request body. CoinCircuit uses a separate base URL with test keys instead — no flag needed. ```diff - https://api.triple-a.io/api/v2 + https://sandbox-api.coincircuit.io/api/v1 ``` Use the **Simulate payment** button on the sandbox checkout page to trigger outcomes (full, partial, overpayment, AML failure) without moving real funds. See the [Sandbox Environment](https://coincircuit.io/guides/sandbox) guide for faucet links and testnet details. --- # Payment Pages | CoinCircuit Docs > Static payment pages with permanent links and QR codes. Source: https://coincircuit.io/docs/guides/payment-pages/ Markdown: https://coincircuit.io/docs/guides/payment-pages.md ## API reference - POST `/api/v1/payments/pages`: [Create a payment page](https://coincircuit.io/api-reference/#tag/payment-pages/POST/api/v1/payments/pages) - GET `/api/v1/payments/pages`: [List payment pages](https://coincircuit.io/api-reference/#tag/payment-pages/GET/api/v1/payments/pages) A payment page is a reusable page with its own link and QR code that takes many payments over time. Share the link online or print the QR code anywhere, and each customer starts their own payment under the same page. Set fixed price options, or let customers enter the amount themselves. ![CoinCircuit payment page — shareable hosted link](https://coincircuit.io/images/features/payment-pages.webp) ## How it works 1. Create a page with `POST /api/v1/payments/pages`, or build it in the dashboard. 2. Print the QR code (light, dark, or grey) for display at your location, or share the link directly. 3. List payments collected by a page with `GET /api/v1/payments/pages/{reference}/sessions`. 4. Update or deactivate the page with `PATCH` / `DELETE /api/v1/payments/pages/{id}`. ## Request fields | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `title` | string | Yes | Page title, up to 50 characters. | | `currency` | string | Yes | `NGN` or `USD`. | | `isActive` | boolean | Yes | Whether the page accepts payments. | | `description` | string | No | Shown to the customer on the page. | | `pricing` | array | No | Fixed price options, each with a `title` and `price`. The customer selects one. | | `enableQuantity` | boolean | No | Adds a quantity selector, e.g. nights or units. Only valid with `pricing` options. | | `minAmount` | number | No | Minimum accepted amount when the customer enters their own. | ![Active payment page with a downloadable QR code](https://coincircuit.io/images/features/payment-pages-qr.webp) Each page has its own analytics: revenue, checkouts, customers, and impressions. ## Use cases - Store counters, market stalls, and pop-ups - Fixed-price products and event tickets - Donations and community dues > Define `pricing` options for set products, or set `minAmount` and let the customer enter the amount. Payments collected through a page send the same webhook events as checkout sessions. --- # Payout Quotes | CoinCircuit Docs > Hold the rate and fee for a payout before you send it. Source: https://coincircuit.io/docs/guides/payout-quotes/ Markdown: https://coincircuit.io/docs/guides/payout-quotes.md ## API reference - POST `/api/v1/payouts/quote`: [Quote a payout](https://coincircuit.io/api-reference/#tag/payouts/POST/api/v1/payouts/quote) - POST `/api/v1/payouts`: [Initiate a payout](https://coincircuit.io/api-reference/#tag/payouts/POST/api/v1/payouts) A quote shows what a payout costs before you send it. Use one when the recipient receives a different currency from the one you pay with, e.g. KES or ETH paid from your USDT balance. The quote holds the rate and the fee for two minutes, and you create the payout at that price. ## How it works 1. Save the recipient with `POST /api/v1/recipients`. 2. Get a quote with `POST /api/v1/payouts/quote`. 3. Create the payout with `POST /api/v1/payouts`, passing the quote's `id` as `quoteId`. 4. Wait for the `payout.success` or `payout.failed` webhook. ## Quote fields | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `currency` | string | Yes | Currency the recipient receives, e.g. `KES` or `ETH`. | | `sourceCurrency` | string | Yes | Stablecoin you pay with, e.g. `USDT`. | | `sourceAmount` | string | Conditional | Amount you pay, in `sourceCurrency`. | | `targetAmount` | string | Conditional | Amount the recipient receives, in `currency`. Accepted when `currency` is a coin, e.g. `ETH`. | | `chain` | string | Conditional | Blockchain the recipient is paid on, e.g. `base`. Required when `currency` is a coin. | Send one of `sourceAmount` and `targetAmount`. ## Get a quote This request prices 100 USDT paid out as ETH on Base. ```http POST https://api.coincircuit.io/api/v1/payouts/quote ``` ```json { "currency": "ETH", "sourceCurrency": "USDT", "chain": "base", "sourceAmount": "100.00" } ``` The response: ```json { "success": true, "message": "Payout quote", "data": { "id": "cpq_2f6b1c8e-9a47-4d3b-b0e5-71c4a8d92f10", "conversion": { "fromCurrency": "USDT", "toCurrency": "ETH", "sourceAmount": "100.00", "sourceFee": "0.50", "targetAmount": "0.03979281", "rate": "0.000397928146" }, "fee": "0.00019896", "total": "0.03999177", "expiresAt": "2026-10-14T09:32:00.000Z" } } ``` | Field | Meaning | | :--- | :--- | | `id` | The quote. Pass it as `quoteId` when you create the payout. | | `conversion.sourceAmount` | What you pay, before the fee. | | `conversion.sourceFee` | The fee, in the currency you pay with. | | `conversion.targetAmount` | What the recipient receives. | | `conversion.rate` | `sourceAmount` x `rate` = `targetAmount`. | | `fee` | The same fee, in the currency the recipient receives. | | `total` | `targetAmount` plus `fee`. | | `expiresAt` | When the quote expires. | Your balance is debited `sourceAmount` plus `sourceFee`: 100.50 USDT here. ### Set what the recipient receives Send `targetAmount` in place of `sourceAmount`. The quote returns what you pay as `conversion.sourceAmount`. ```json { "currency": "ETH", "sourceCurrency": "USDT", "chain": "base", "targetAmount": "0.04000000" } ``` ### Cross-border currencies Quote a cross-border currency by `sourceAmount`. Cross-border payouts are available to verified businesses. ```json { "currency": "KES", "sourceCurrency": "USDT", "sourceAmount": "100.00" } ``` ## Create the payout Pass the quote's `id` as `quoteId`. The quote sets the amount. ```http POST https://api.coincircuit.io/api/v1/payouts ``` ```json { "currency": "ETH", "sourceCurrency": "USDT", "quoteId": "cpq_2f6b1c8e-9a47-4d3b-b0e5-71c4a8d92f10", "recipientId": "8d3f5a17-6c2e-4b9a-a1f4-0e7d92c5b386" } ``` The response: ```json { "success": true, "message": "Crypto payout initialized successfully", "data": { "id": "5b0e7c94-2a61-4f38-9d15-c3a8f6e1b472", "reference": "CPAY-6KD2QX-T4BN1WCE5RJY7H3MZ0V9A2PL", "method": "crypto", "status": "pending", "amount": "0.03979281", "fee": "0.00019896", "total": "0.03999177", "currency": "ETH", "conversion": { "fromCurrency": "USDT", "toCurrency": "ETH", "sourceAmount": "100.00", "sourceFee": "0.50", "targetAmount": "0.03979281", "rate": "0.000397928146" }, "narration": "Payout transfer", "recipient": { "id": "8d3f5a17-6c2e-4b9a-a1f4-0e7d92c5b386", "type": "crypto_address", "details": { "chain": "base", "address": "0x7a3b9c2d4e5f60718293a4b5c6d7e8f901234567" } }, "channel": "api", "txHash": null, "sessionId": null, "failureReason": null, "completedAt": null, "createdAt": "2026-10-14T09:30:41.207Z", "updatedAt": "2026-10-14T09:30:41.352Z" } } ``` A `payout.success` webhook confirms the transfer. `GET /api/v1/payouts/{id}` then returns its `txHash`. ## When a quote is refused A quote works once and lasts two minutes. The payout request returns a `400` asking for a new quote when: - the quote has expired or been used - the price has moved since the quote - `sourceCurrency` or the recipient's blockchain differs from the quote Get a new quote and send the payout again. ## Pay out at the current rate Send `amount` in place of `quoteId`. `amount` is what the recipient receives, in `currency`, and the payout is priced when you create it. ## Use cases - Showing a customer the cost before they confirm - Paying staff or suppliers in the coin they ask for - Sending mobile money from a stablecoin balance > Blockchain transfers cannot be reversed. Validate the recipient with `POST /api/v1/recipients/validate` before you send. --- # Payouts | CoinCircuit Docs > Withdraw your balance to a bank account or any crypto wallet. Source: https://coincircuit.io/docs/guides/payouts/ Markdown: https://coincircuit.io/docs/guides/payouts.md ## API reference - POST `/api/v1/recipients`: [Save a recipient](https://coincircuit.io/api-reference/#tag/payout-recipients/POST/api/v1/recipients) - POST `/api/v1/payouts`: [Initiate a payout](https://coincircuit.io/api-reference/#tag/payouts/POST/api/v1/payouts) - GET `/api/v1/payouts`: [List payouts](https://coincircuit.io/api-reference/#tag/payouts/GET/api/v1/payouts) A payout moves money out of your balance to someone else. Send crypto to any wallet address, cash out to a bank account, or pay a mobile money account across Africa. You choose the amount and destination, CoinCircuit shows the fee before you confirm, then sends the funds. ![Payout to a bank or crypto wallet](https://coincircuit.io/images/features/payouts.png) ## How it works 1. Save a recipient once with `POST /api/v1/recipients`: a crypto address, a bank account, or a mobile money account. 2. Check the cost with `GET /api/v1/payouts/fees`, or get a quote with `POST /api/v1/payouts/quote` when the recipient receives a different currency from the one you pay with, e.g. KES. 3. Create the payout with `POST /api/v1/payouts` (currency, amount, recipientId). 4. Track it with `GET /api/v1/payouts` and `GET /api/v1/payouts/{id}`. A `payout.success` or `payout.failed` webhook tells you the result. ## Supported currencies | Currency | Recipient type | Delivered as | | :--- | :--- | :--- | | ![](https://coincircuit.io/assets/crypto/usdt.svg) USDT / ![](https://coincircuit.io/assets/crypto/usdc.svg) USDC | `crypto_address` | Crypto transfer to any wallet | | ![](https://coincircuit.io/assets/flags/NG.svg) NGN | `ngn_bank_account` | Bank transfer to any Nigerian bank | | ![](https://coincircuit.io/assets/flags/KE.svg) KES | `kes_mobile_money` | M-Pesa mobile money | | ![](https://coincircuit.io/assets/flags/GH.svg) GHS | `ghs_mobile_money` | MTN mobile money | | ![](https://coincircuit.io/assets/flags/US.svg) USD | Coming soon | ACH bank transfer | | ![](https://coincircuit.io/assets/flags/CM.svg) XAF | Coming soon | Coming soon | | ![](https://coincircuit.io/assets/flags/UG.svg) UGX | Coming soon | Coming soon | ## Use cases - Settling earnings to your bank - Paying suppliers, staff, or vendors in crypto - Moving balances to treasury wallets > Validate a recipient's details with `POST /api/v1/recipients/validate` before you send. Blockchain transfers cannot be reversed. --- # POS Terminals | CoinCircuit Docs > Accept in-person crypto payments at the point of sale. Source: https://coincircuit.io/docs/guides/pos-terminals/ Markdown: https://coincircuit.io/docs/guides/pos-terminals.md A POS terminal lets you take crypto payments in person, on any phone or tablet at your counter. You enter the amount, the customer scans the QR code on screen, and the payment confirms on the spot. It also runs on traditional Android POS devices with a built-in receipt printer, so you can print a receipt for the customer after each payment. Install the app on your device to get started: [download the POS app for Android](https://coincircuit-pos-releases.s3.eu-north-1.amazonaws.com/pos/coincircuit-pos.apk). ![CoinCircuit POS terminal for in-store QR payments](https://coincircuit.io/images/features/pos-terminals.webp) ## How it works 1. In the dashboard, create a terminal and link it to a payment page. 2. Generate a setup code and enter it on the POS device to pair it. 3. At the register, the terminal shows a QR code and a countdown for the amount due. 4. The customer scans and pays, and the terminal confirms the payment on screen. 5. Review payments per device in the dashboard. Name the terminal and select the payment page it charges through: ![Creating a POS terminal and linking a payment page](https://coincircuit.io/images/features/pos-terminals-create.webp) Pair a device with a short-lived setup code: ![Terminal pairing with a setup code](https://coincircuit.io/images/features/pos-terminals-pairing.webp) ## Use cases - Retail counters and pop-up stalls - Cafés, bars, and restaurants - Markets and events with multiple staff devices > POS terminals are set up in the dashboard, not the public API. Each terminal tracks its own payments. --- # Refund & Dispute Handling | CoinCircuit Docs > Refund checkout sessions and invoices in crypto. Source: https://coincircuit.io/docs/guides/refund-management/ Markdown: https://coincircuit.io/docs/guides/refund-management.md Tags: Refunds, Webhooks, Support Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me add refund handling to my existing CoinCircuit payment integration. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `search_api` with feature `Refunds` in the CoinCircuit MCP to see all available refund endpoints (estimate, create session refund, create invoice refund, list, get by ID). - Call `get_endpoint` with method `post` and path `/api/v1/refunds/session/{sessionReference}` for the session refund request/response schema. - Call `get_endpoint` with method `post` and path `/api/v1/refunds/invoice/{invoiceReference}` for the invoice refund schema. - Call `get_endpoint` with method `get` and path `/api/v1/refunds/estimate/{reference}` for the refund estimation schema. - Call `get_schema` with name `RefundCreatedWebhookDto` for the refund.created webhook payload. - Call `get_schema` with name `RefundSuccessWebhookDto` for the refund.success webhook payload. - Call `get_schema` with name `RefundFailedWebhookDto` for the refund.failed webhook payload. - Call `get_schema` with name `RefundResponseDto` for the full refund object shape used in both API responses and webhooks. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have an application using CoinCircuit for payments and I need to handle customer refund requests for both checkout session payments and invoice payments. CoinCircuit sends crypto refunds to a wallet address you specify. ## What I Need You to Implement ### 1. Estimate refund before processing Before issuing a refund, show the customer what they'll receive after fees. **Endpoint:** `GET /api/v1/refunds/estimate/{reference}?entity={type}` *(Call `get_endpoint` with method `get`, path `/api/v1/refunds/estimate/{reference}` in the CoinCircuit MCP for the full parameter and response details.)* **Path params:** - `reference` (string) - the session reference (e.g. `CS_1234567890`) or invoice reference (e.g. `INV_1234567890`) **Query params:** - `entity` (required) - `"session"` or `"invoice"` - `feePaidBy` (optional) - `"merchant"` or `"customer"` **Response (200):** - `data.customerReceives` - what the customer gets: `amount`, `asset`, `chain` - `data.fees.amount` - fee in the refund asset - `data.fees.asset` - asset the fee is charged in - `data.fees.fiatAmount` - the same fee in the currency your payments settle into - `data.fees.fiatCurrency` - currency of `fiatAmount` - `data.fees.paidBy` - `"customer"` or `"merchant"` - `data.customerPaid` - the original payment: `cryptoAmount`, `asset`, `fiatAmount`, `fiatCurrency` - `data.merchantCost` - what is debited from your balance: `amount`, `currency`. Already includes the fee when `paidBy` is `"merchant"`. - `data.conversionRate` - price of one unit of the refund asset in `merchantCost.currency` - `data.balanceSource` - `"settled"` or `"pending"`. `"pending"` means the original payment was never added to your balance. **Example:** ```json { "success": true, "message": "Estimation retrieved successfully", "data": { "customerReceives": { "amount": "0.50098255", "asset": "SOL", "chain": "solana" }, "fees": { "amount": "0.01038637", "asset": "SOL", "fiatAmount": "1.00", "fiatCurrency": "USDT", "paidBy": "customer" }, "customerPaid": { "cryptoAmount": "0.52140427", "asset": "SOL", "fiatAmount": "50.00", "fiatCurrency": "USD" }, "merchantCost": { "amount": "50.00", "currency": "USDT" }, "conversionRate": "97.77676674533762", "balanceSource": "settled" } } ``` Use `customerReceives` and `fees` for a confirmation screen, e.g. "Network fee: 0.01038637 SOL (1.00 USDT), Customer receives: 0.50098255 SOL". ### 2. Refund a checkout session **Endpoint:** `POST /api/v1/refunds/session/{sessionReference}` *(Call `get_endpoint` with method `post`, path `/api/v1/refunds/session/{sessionReference}`, section `request` in the CoinCircuit MCP for the exact request body.)* **Path params:** - `sessionReference` (string) - the session reference from the original payment **Request body:** - `refundAddress` (string, **required**) - the customer's wallet address to receive the refund - `reason` (string, optional) - e.g. "Customer requested refund", "Product not delivered" - `feePaidBy` (string, optional) - `"merchant"` or `"customer"`. Defaults to your dashboard settings. Controls who absorbs the blockchain gas fee. **Example:** ```json { "refundAddress": "TF6yMCJqFcT6wFFutxVmRocKgJFD5imKUT", "reason": "Customer requested refund - product not as described", "feePaidBy": "merchant" } ``` **Response (201):** Returns the refund object: - `data.id` - refund UUID - `data.entity` - `"session"` - `data.reference` - the session reference - `data.status` - `"pending"`, `"processing"`, `"completed"`, or `"failed"` - `data.chain` - blockchain used for the refund (matches original payment) - `data.asset` - crypto asset (e.g. `"USDT"`) - `data.amount` - crypto amount the customer receives (e.g. `"49.50000000"`) - `data.fee` - network fee in crypto (e.g. `"0.50000000"`) - `data.feePaidBy` - `"merchant"` or `"customer"` - `data.balanceSource` - `"settledBalance"` or `"pendingBalance"` - `data.merchantDebitAmount` - fiat amount debited from your balance - `data.fiatAmount` / `data.fiatCurrency` - fiat value of the refund - `data.refundAddress` - customer's wallet - `data.txHash` - blockchain tx hash (populated on completion) - `data.explorerUrl` - block explorer link (populated on completion) *(Call `get_schema` with name `RefundResponseDto` in the CoinCircuit MCP for every field in the refund object, including which are required vs optional.)* ### 3. Refund an invoice **Endpoint:** `POST /api/v1/refunds/invoice/{invoiceReference}` *(Call `get_endpoint` with method `post`, path `/api/v1/refunds/invoice/{invoiceReference}` in the CoinCircuit MCP for the full schema.)* Same request body as session refunds: `refundAddress` (required), `reason` (optional), `feePaidBy` (optional). Same response shape. ### 4. Track refund status via webhooks *(Call `get_schema` with name `RefundSuccessWebhookDto` in the CoinCircuit MCP for the full refund.success webhook payload. Call `get_schema` with name `RefundFailedWebhookDto` for the failure payload.)* **Refund events** (envelope: `{ event: string, data: { refund: RefundObject } }`): - `refund.created` - refund initiated, blockchain transaction pending. `data.refund.status` is `"pending"`. *(Call `get_schema` with name `RefundCreatedWebhookDto` for the full payload.)* - `refund.success` - crypto sent to customer's wallet. `data.refund.txHash` and `data.refund.explorerUrl` are populated. `data.refund.completedAt` has the timestamp. - `refund.failed` - refund failed (e.g. invalid refund address). `data.refund.status` is `"failed"`. **Refund object fields in webhook:** - `data.refund.id` - refund UUID - `data.refund.entity` - `"session"` or `"invoice"` - `data.refund.reference` - original session/invoice reference - `data.refund.status` - `"pending"`, `"processing"`, `"completed"`, `"failed"` - `data.refund.amount` - crypto amount customer receives - `data.refund.fee` - network fee - `data.refund.feePaidBy` - who paid the fee - `data.refund.refundAddress` - customer's wallet - `data.refund.txHash` - blockchain tx hash (on success) - `data.refund.explorerUrl` - block explorer URL (on success) - `data.refund.merchantDebitAmount` - fiat amount debited from merchant - `data.refund.fiatAmount` / `data.refund.fiatCurrency` - fiat value ### 5. Query refund history *(Call `search_api` with feature `Refunds` in the CoinCircuit MCP to see all listing and detail endpoints.)* **List all refunds:** `GET /api/v1/refunds` (returns paginated list) *(Call `get_endpoint` with method `get`, path `/api/v1/refunds` in the CoinCircuit MCP for pagination params and response schema.)* **Get single refund:** `GET /api/v1/refunds/{id}` *(Call `get_endpoint` with method `get`, path `/api/v1/refunds/{id}` in the CoinCircuit MCP for the full response.)* Use these to build a support dashboard showing all refunds with their status, amounts, and transaction details. ### 6. Customer communication flow Build email/notification triggers based on webhook events: - On `refund.created`: "Your refund has been initiated. We're sending {amount} {asset} to your wallet." - On `refund.success`: "Your refund of {amount} {asset} has been sent to {refundAddress}. Track it here: {explorerUrl}" - On `refund.failed`: "We encountered an issue processing your refund. Our team is looking into it. Reference: {reference}" ## Constraints - `refundAddress` is **required**. CoinCircuit needs to know where to send the crypto. - Refunds are async. The API returns immediately with `"pending"` status. Use webhooks for final status. - A session or invoice can only be refunded **once**. - You cannot refund more than the original payment amount. - The refund is sent in crypto (on the same chain/asset as the original payment) regardless of the original fiat denomination. - Network fees (gas) may be deducted from the refund amount (if `feePaidBy: "customer"`) or from your merchant balance (if `feePaidBy: "merchant"`). - Use the estimate endpoint first to show the customer what they'll receive. - Refund statuses: `"pending"` -> `"processing"` -> `"completed"` or `"failed"`. --- # Refunds | CoinCircuit Docs > Refund paid sessions and invoice. Source: https://coincircuit.io/docs/guides/refunds/ Markdown: https://coincircuit.io/docs/guides/refunds.md ## API reference - POST `/api/v1/refunds/session/{sessionReference}`: [Refund a payment](https://coincircuit.io/api-reference/#tag/refunds/POST/api/v1/refunds/session/{sessionReference}) - POST `/api/v1/refunds/invoice/{invoiceReference}`: [Refund an invoice](https://coincircuit.io/api-reference/#tag/refunds/POST/api/v1/refunds/invoice/{invoiceReference}) - GET `/api/v1/refunds`: [List refunds](https://coincircuit.io/api-reference/#tag/refunds/GET/api/v1/refunds) A refund returns crypto to a customer for a payment or invoice they already made. CoinCircuit already knows the original amount and asset, so you only give the wallet address to send it to. The refund settles on the blockchain, and a webhook confirms when the customer has the funds. It comes out of your settled balance, except for a refund of an underpayment you never accepted, which is not debited because those funds were never credited there. ![CoinCircuit refund — original payment and refund amount](https://coincircuit.io/images/features/refunds.webp) ## How it works 1. Estimate the cost with `GET /api/v1/refunds/estimate/{reference}?entity=session|invoice`. The estimate includes network fees. 2. Refund a session with `POST /api/v1/refunds/session/{sessionReference}`, or an invoice with `POST /api/v1/refunds/invoice/{invoiceReference}`. 3. Track status with `GET /api/v1/refunds` and `GET /api/v1/refunds/{id}`. ## Request fields | Field | Type | Required | Description | | :--- | :--- | :--- | :--- | | `refundAddress` | string | Yes | Customer wallet address that receives the refund. | | `reason` | string | No | Reason for the refund. | | `feePaidBy` | string | No | Who pays the network fee: `merchant` or `customer`. Defaults to your merchant settings. | ## Webhook events | Event | Sent when | | :--- | :--- | | `refund.created` | The refund is initiated. | | `refund.success` | The refund is confirmed on-chain. | | `refund.failed` | The refund could not be completed. | ## Use cases - Cancelled orders and returns - Overpayments and duplicate charges - Dispute resolution and goodwill credits > Refunds are paid from your balance. Run the estimate first to see the net cost, including network fees. --- # SaaS Invoice Billing | CoinCircuit Docs > Bill subscriptions with crypto invoices, expiry timers, and partial payments. Source: https://coincircuit.io/docs/guides/saas-invoicing/ Markdown: https://coincircuit.io/docs/guides/saas-invoicing.md Tags: Invoices, Webhooks Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me integrate CoinCircuit crypto invoicing into my existing SaaS billing system. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_endpoint` with method `post` and path `/api/v1/invoices` in the CoinCircuit MCP for the full invoice creation schema. - Call `search_api` with query `invoice webhook` and type `schemas` to list all invoice webhook payload schemas. - Call `get_schema` with name `InvoicePaidWebhookDto` for the exact invoice.paid webhook payload. - Call `get_schema` with name `InvoiceExpiredWebhookDto` for the invoice.expired webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have a SaaS app that bills customers monthly. I'm adding crypto invoice payments via CoinCircuit so customers can pay in any supported crypto (USDT, BTC, ETH, etc.). ## What I Need You to Implement ### 1. Invoice creation on subscription renewal **Endpoint:** `POST /api/v1/invoices` *(Call `get_endpoint` with method `post`, path `/api/v1/invoices`, section `request` in the CoinCircuit MCP for the exact request body schema with all field types and validations.)* **Required fields:** - `amount` (string) - the subscription price as a string with up to 2 decimal places, e.g. `"29.99"` - `currency` (string) - `"NGN"` or `"USD"` - `description` (string) - e.g. "Pro Plan - May 2026" - `expiresAt` (string, ISO 8601) - when the invoice expires. Max 2 days from creation. Defaults to 12 hours if omitted. - `customer` (object) - must include `email` (required). Optional: `firstName`, `lastName`, `phone` (E.164), `telegramId` **Optional fields:** - `reference` (string) - custom invoice reference, e.g. `"INV-2026-005"`. Auto-generated if omitted. - `periodStart` / `periodEnd` (string, ISO 8601) - billing period dates for subscription context - `nextPaymentDate` (string, ISO 8601) - next billing date, shown on the invoice - `metadata` (object) - store `subscriptionId`, `plan`, etc. for webhook reconciliation - `successUrl` / `cancelUrl` (string) - redirect URLs after payment - `asset` (string) - lock to a specific crypto (`"BTC"`, `"ETH"`, `"USDT"`, `"USDC"`, `"SOL"`, `"BNB"`, `"TRX"`) - `chain` (string) - lock to a specific blockchain (`"bitcoin"`, `"ethereum"`, `"solana"`, `"bsc"`, `"tron"`, `"base"`, `"arbitrum"`) **Example request body:** ```json { "amount": "29.99", "currency": "USD", "description": "Pro Plan - May 2026", "expiresAt": "2026-05-03T00:00:00.000Z", "customer": { "email": "subscriber@example.com", "firstName": "John", "lastName": "Doe" }, "periodStart": "2026-05-01T00:00:00.000Z", "periodEnd": "2026-05-31T23:59:59.000Z", "nextPaymentDate": "2026-06-01T00:00:00.000Z", "metadata": { "subscriptionId": "sub_abc123", "plan": "pro" }, "successUrl": "https://myapp.com/billing/success" } ``` **Response (201):** Returns the invoice object. Key fields: - `data.id` - invoice UUID - `data.reference` - invoice reference (e.g. `"inv_ref_abc123xyz789"`) - `data.url` - payment URL (e.g. `https://checkout.coincircuit.io/invoice/inv-abc123`) - `data.status` - starts as `"pending"`, transitions to `"partial"`, `"paid"`, or `"expired"` - `data.state` - `"open"` (accepting payments) or `"closed"` (finalized) - `data.amount` / `data.amountPaid` - track payment progress - `data.isRefunded` - boolean *(Call `get_endpoint` with method `post`, path `/api/v1/invoices`, section `success` in the CoinCircuit MCP for the full response schema.)* **Error responses:** 400 (invalid input or expiresAt exceeds 2 days), 401 (bad API key) ### 2. Send the payment link The response includes `data.url`. Email this to the customer or display it in your app's billing dashboard. The hosted page handles crypto selection, address display, and payment detection automatically. ### 3. Webhook event handling *(Call `get_schema` with name `InvoicePaidWebhookDto` in the CoinCircuit MCP for the full invoice.paid webhook payload with all nested fields including the payments array.)* **Invoice events** (envelope: `{ event: string, data: { invoice: InvoiceObject, payments?: PaymentArray } }`): - `invoice.created` - confirmation the invoice was created. Good for logging. *(Call `get_schema` with name `InvoiceCreatedWebhookDto` for details.)* - `invoice.paid` - full payment received. **Activate or extend the subscription.** The `data.payments` array contains details on each payment session: `asset`, `chain`, `amount`, `address`, `txHash`, `explorerUrl`, `status`. - `invoice.updated` - partial payment received. Check `data.invoice.amountPaid` vs `data.invoice.amount` to track progress. `data.invoice.status` will be `"partial"`. *(Call `get_schema` with name `InvoiceUpdatedWebhookDto` for details.)* - `invoice.expired` - invoice expired unpaid. Suspend access or create a new invoice with a reminder email. *(Call `get_schema` with name `InvoiceExpiredWebhookDto` for details.)* **Invoice webhook data fields:** - `data.invoice.reference` - matches your invoice - `data.invoice.metadata` - your `subscriptionId` and `plan` are here - `data.invoice.amount` / `data.invoice.amountPaid` - track cumulative payments - `data.invoice.status` - `"pending"`, `"partial"`, `"paid"`, `"expired"` - `data.invoice.paidAt` - ISO 8601 timestamp when fully paid - `data.invoice.periodStart` / `data.invoice.periodEnd` - billing period - `data.invoice.customer.email` - for confirmation emails **Webhook security:** Same as checkout: verify HMAC-SHA256 via `x-coincircuit-signature`, deduplicate via `x-coincircuit-delivery-id`. ## Constraints - Invoice `amount` is a **string** with up to 2 decimal places (e.g. `"29.99"`), same as checkout sessions - `expiresAt` max is 2 days from creation. Defaults to 12 hours. - Invoices support partial payments. Track `amountPaid` before activating the subscription. - The invoice stays `"open"` until fully paid or expired - Supported currencies: NGN, USD --- # Sandbox Environment | CoinCircuit Docs > Test safely with sandbox keys and testnet faucets. Source: https://coincircuit.io/docs/guides/sandbox/ Markdown: https://coincircuit.io/docs/guides/sandbox.md Run your full integration against the sandbox before going live: the same API behavior on testnet, with no real funds at stake. ## Base URLs - **Production:** `https://api.coincircuit.io` - **Sandbox:** `https://sandbox-api.coincircuit.io` Use sandbox (test) API keys against the sandbox base URL. Live keys only work against production. ## Testnets Sandbox payments settle on each blockchain's test network: - **Tron:** Nile - **Ethereum:** Sepolia - **Solana:** Devnet ## Testnet faucets Get free testnet tokens to fund sandbox payments. ### Tron (recommended) Install the [TronLink](https://www.tronlink.org/) wallet, then claim testnet TRX and USDT from the Nile faucet at [nileex.io/join/getJoinPage](https://nileex.io/join/getJoinPage). ### Ethereum (Sepolia) Claim Sepolia testnet ETH from the [Google Cloud faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia). ### Solana Claim devnet SOL from [faucet.solana.com](https://faucet.solana.com/). ## Simulate payments from the checkout page When your integration runs against the sandbox, the checkout page shows a **Simulate payment** button in the bottom-right corner. ![A sandbox checkout session with the Simulate payment panel open, listing the available payment outcomes](https://coincircuit.io/images/guides/sandbox-simulate-payment.png) Use it to trigger a payment outcome for the open session without moving real funds: - **Full payment:** completes the session. - **Underpayment:** a partial deposit, 50% of the amount. - **Overpayment:** an excess deposit, 150% of the amount. - **AML failure:** a deposit from a sanctioned sender that fails screening. Enter a custom amount if you want a specific value. Select an asset and network first so the session has a deposit address to pay into. --- # Stablecoin On/Off-Ramp | CoinCircuit Docs > Convert between fiat (NGN) and stablecoins (USDC or USDT). Source: https://coincircuit.io/docs/guides/stablecoin-onramp-offramp/ Markdown: https://coincircuit.io/docs/guides/stablecoin-onramp-offramp.md Tags: Swap, Balance, Payouts Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me build a stablecoin on-ramp and off-ramp into my existing application using CoinCircuit swaps. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_api_overview` in the CoinCircuit MCP for base URLs, auth method, and available features. - Call `search_api` with query `swap` and type `endpoints` to list all swap endpoints (estimate, quotation, execute, history). - Call `get_endpoint` with method `get` and path `/api/v1/swap/estimate` for the indicative estimate schema. - Call `get_endpoint` with method `post` and path `/api/v1/swap/quotation` for the locked-rate quotation schema. - Call `get_endpoint` with method `post` and path `/api/v1/swap/execute/{quotationId}` for the execute schema. - Call `get_endpoint` with method `get` and path `/api/v1/balance` for the balance response schema. - Call `get_endpoint` with method `post` and path `/api/v1/payouts` for the payout (off-ramp withdrawal) schema. - Call `get_conversion_rate` in the CoinCircuit MCP for live display rates. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL (production):** `https://api.coincircuit.io` - **Base URL (sandbox):** `https://sandbox-api.coincircuit.io` - **Auth:** Pass your API key in the `x-api-key` header on every request. ## Project Context I want users to move between fiat and stablecoins held in my CoinCircuit merchant balance: - **On-ramp:** fiat (NGN) -> stablecoin (USDC or USDT) - **Off-ramp:** stablecoin (USDC or USDT) -> fiat (NGN), then withdraw to a bank account Swaps convert between two currencies in your CoinCircuit balance at a rate you lock in advance. Supported balance currencies for swaps are `NGN` and a stablecoin (`USDC` or `USDT`). The flow is always: get a quote -> lock a quotation -> execute before it expires. ## What I Need You to Implement ### 1. Check the balance **Endpoint:** `GET /api/v1/balance?currency={currency}` *(Call `get_endpoint` with method `get`, path `/api/v1/balance` in the CoinCircuit MCP for the full response schema.)* - `currency` (optional) - `"NGN"` or your stablecoin (`"USDC"` or `"USDT"`). If omitted, returns your default currency balance. Confirm `availableBalance` covers the amount you intend to swap before requesting a quotation. ### 2. Get an indicative estimate (optional) Show the user roughly what they'll get before committing. This rate is **indicative only**, not locked. **Endpoint:** `GET /api/v1/swap/estimate?fromCurrency={from}&toCurrency={to}&amount={amount}` *(Call `get_endpoint` with method `get`, path `/api/v1/swap/estimate` in the CoinCircuit MCP for the full response schema.)* **Query params:** - `fromCurrency` - `"NGN"` or your stablecoin (`"USDC"` or `"USDT"`) - `toCurrency` - the other side - `amount` (string) - amount to swap, up to 2 decimal places, e.g. `"100.00"` **Response (200):** `fromCurrency`, `toCurrency`, `sourceAmount`, `targetAmount`, `rate`. Example: on-ramp 100,000 NGN into a stablecoin, or off-ramp 100.00 USDC/USDT into NGN. ### 3. Create a locked quotation When the user commits, lock the rate. **Endpoint:** `POST /api/v1/swap/quotation` *(Call `get_endpoint` with method `post`, path `/api/v1/swap/quotation`, section `request` in the CoinCircuit MCP for the exact request body.)* **Request body:** ```json { "fromCurrency": "USDC", "toCurrency": "NGN", "amount": "100.00" } ``` **Response (201):** Returns the quotation: - `data.id` - the quotation ID (pass this to execute) - `data.fromCurrency` / `data.toCurrency` - `data.sourceAmount` / `data.targetAmount` - `data.rate` - the locked rate - `data.expiresAt` - **the quotation expires within seconds.** Execute promptly. - `data.executed` - `false` until executed *(Call `get_endpoint` with method `post`, path `/api/v1/swap/quotation`, section `success` in the CoinCircuit MCP for the full response schema.)* ### 4. Execute the swap **Endpoint:** `POST /api/v1/swap/execute/{quotationId}` *(Call `get_endpoint` with method `post`, path `/api/v1/swap/execute/{quotationId}` in the CoinCircuit MCP for the full schema.)* No request body. Pass the `quotationId` from step 3 in the path. CoinCircuit atomically debits the source currency and credits the target currency at the locked rate. **Response (200):** Returns the completed swap: - `data.id` - swap ID - `data.fromCurrency` / `data.toCurrency` - `data.sourceAmount` / `data.targetAmount` - `data.rate` - `data.status` - `"completed"` - `data.completedAt` **Errors:** 400 (quotation expired, already used, or insufficient balance), 404 (quotation not found). ### 5. Withdraw fiat to a bank account (complete the off-ramp) After swapping a stablecoin into NGN, move the NGN out to a bank account. **Endpoint:** `POST /api/v1/payouts` with `method: "fiat"` *(Call `get_endpoint` with method `post`, path `/api/v1/payouts` in the CoinCircuit MCP for the request body and the bank-account recipient setup.)* Fiat payouts settle to the merchant's own registered bank account. Track them with `payout.success` / `payout.failed` webhooks. ### 6. Review swap history - **List:** `GET /api/v1/swaps` (paginated) - **Get one:** `GET /api/v1/swaps/{id}` *(Call `get_endpoint` with method `get`, path `/api/v1/swaps` in the CoinCircuit MCP for pagination params and the response schema.)* ### Ramp Flow Summary ``` On-ramp: Bank transfer -> NGN balance -> POST /swap/quotation (NGN -> USDC/USDT) -> POST /swap/execute -> stablecoin balance Off-ramp: Stablecoin balance -> POST /swap/quotation (USDC/USDT -> NGN) -> POST /swap/execute -> NGN balance -> POST /payouts (fiat) -> bank ``` ## Constraints - Supported swap currencies are `NGN` and a stablecoin (`USDC` or `USDT`). `amount` is a **string** with up to 2 decimal places (e.g. `"100.00"`). - The estimate is a preview only. The rate is locked when you create a quotation. - **Quotations expire within seconds.** Create the quotation immediately before executing, and handle the "expired" error by re-quoting. - A quotation can only be executed **once**. Re-executing a used quotation returns a 400. - Show users the `targetAmount` from the quotation. That is the exact amount they receive at the locked rate. - Always check `availableBalance` for the source currency before quoting. --- # Swaps | CoinCircuit Docs > Convert between fiat and stablecoins on your balance (on and off ramp). Source: https://coincircuit.io/docs/guides/swaps/ Markdown: https://coincircuit.io/docs/guides/swaps.md ## API reference - GET `/api/v1/swap/estimate`: [Estimate a swap](https://coincircuit.io/api-reference/#tag/swap/GET/api/v1/swap/estimate) - POST `/api/v1/swap/quotation`: [Create a quotation](https://coincircuit.io/api-reference/#tag/swap/POST/api/v1/swap/quotation) - POST `/api/v1/swap/execute/{quotationId}`: [Execute a swap](https://coincircuit.io/api-reference/#tag/swap/POST/api/v1/swap/execute/{quotationId}) - GET `/api/v1/swaps`: [List swaps](https://coincircuit.io/api-reference/#tag/swap/GET/api/v1/swaps) A swap converts from one currency to another at a rate you lock first. Move between a stablecoin (USDC or USDT) and fiat (NGN) to turn crypto you have received into cash, or to top up stablecoins to pay out. You get a quote, lock it, and CoinCircuit settles the conversion on your balance. ![Swap between assets](https://coincircuit.io/images/features/swaps.png) ## How it works 1. Check the rate with `GET /api/v1/swap/estimate`. 2. Lock a quote with `POST /api/v1/swap/quotation` (returns a `quotationId` with a short expiry). 3. Re-check a quote with `GET /api/v1/swap/quotation/{quotationId}`. 4. Execute before it expires with `POST /api/v1/swap/execute/{quotationId}`. 5. List swaps with `GET /api/v1/swaps` and `GET /api/v1/swaps/{id}`. ## Use cases - Converting to stablecoins after a sale - Moving the same asset across chains - Preparing an asset for a payout > A quote expires after a short time. Execute it before then, or request a new one. --- # Telegram Bot Crypto Payments | CoinCircuit Docs > Take crypto payments in a Telegram bot for subscriptions or access. Source: https://coincircuit.io/docs/guides/telegram-subscription-bot/ Markdown: https://coincircuit.io/docs/guides/telegram-subscription-bot.md Tags: Telegram, Payments, Webhooks, Node.js Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me integrate CoinCircuit crypto payments into my existing Telegram bot. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_api_overview` in the CoinCircuit MCP for base URLs, auth method, and available features. - Call `get_endpoint` with method `post` and path `/api/v1/payments` for the full payment session creation schema. - Call `search_api` with query `webhook` and type `schemas` to list all webhook payload schemas. - Call `get_schema` with name `PaymentCompletedWebhookDto` for the exact payment.completed webhook payload. - Call `get_schema` with name `TransactionReceivedWebhookDto` for the transaction.received webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL (production):** `https://api.coincircuit.io` - **Base URL (sandbox):** `https://sandbox-api.coincircuit.io` - **Auth:** Pass your API key in the `x-api-key` header on every request. ## Project Context I have an existing Telegram bot and I want to add crypto payment support using CoinCircuit. The integration should: 1. Create a CoinCircuit payment session when a user wants to pay 2. Send the hosted checkout URL to the user in chat 3. Listen for payment confirmation via webhook 4. Trigger the appropriate action in my bot (grant access, deliver content, activate subscription, etc.) This pattern works for any Telegram bot use case: subscription access, one-time purchases, premium features, tip jars, or pay-per-use commands. ## What I Need You to Implement ### 1. Create a payment session from a bot command When a user triggers a payment (e.g. via a command or button callback), create a CoinCircuit payment session from your bot's backend: **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `request` in the CoinCircuit MCP for the exact request body schema.)* **Required fields:** - `title` (string) - e.g. "Premium Channel - 30 Days" - `description` (string) - e.g. "Subscription payment for premium access" - `amount` (string) - subscription price as a string, e.g. `"9.99"` - `currency` (string) - `"USD"` or `"NGN"` - `customer` (object) - must include `email` (required). Include `telegramId` for linking. **Optional fields:** - `metadata` (object) - store `telegramUserId`, `telegramUsername`, `plan`, `channelId`, `subscriptionPeriodEnd` for webhook reconciliation - `successUrl` (string) - redirect after payment (HTTPS) - `cancelUrl` (string) - redirect if cancelled - `webhookUrl` (string) - per-session webhook URL override (HTTPS) - `asset` (string) - lock to a specific crypto: `"BTC"`, `"ETH"`, `"USDT"`, `"USDC"`, `"SOL"`, `"BNB"`, `"TRX"` - `chain` (string) - lock to a specific blockchain: `"bitcoin"`, `"ethereum"`, `"solana"`, `"bsc"`, `"tron"`, `"base"`, `"arbitrum"` **Example request body:** ```json { "title": "Premium Channel - 30 Days", "description": "Subscription payment for premium Telegram access", "amount": "9.99", "currency": "USD", "customer": { "email": "user@example.com", "telegramId": "123456789" }, "metadata": { "telegramUserId": "123456789", "telegramUsername": "johndoe", "plan": "premium-monthly", "channelId": "-1001234567890", "subscriptionPeriodEnd": "2026-04-30T23:59:59.000Z" }, "successUrl": "https://mybot.com/subscription/success" } ``` **Response (201):** Returns a session object. Key fields: - `data.reference` - session reference (store this alongside the subscription) - `data.url` - hosted checkout page URL. **Send this to the user via Telegram.** - `data.payment.status` - starts as `"pending"` - `data.expiresAt` - session expiration timestamp *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `success` in the CoinCircuit MCP for the full response schema.)* ### 2. Send checkout link to the user After creating the session, send the `data.url` to the user in chat. The hosted checkout page handles crypto selection, address display, and payment detection automatically. No additional frontend work needed. ### 3. Webhook handler: process payment confirmation Set up an endpoint to receive CoinCircuit webhooks. This is where your bot takes action after payment. *(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP for the full payload.)* **Payment events** (envelope: `{ event: string, data: { session: PaymentSession } }`): - `payment.completed` - full payment confirmed. **This is your trigger to take action in your bot.** - Read `data.session.metadata.telegramUserId` to identify the user - Read `data.session.metadata` for any custom data you stored (plan, product, channel ID, etc.) - Execute your bot's logic: grant access, send a file, activate a feature, update a subscription, etc. - `payment.expired` - session expired before payment. Optionally notify the user and offer a new session. - `payment.partial` - customer sent crypto but not enough. The session stays open for more payments. - `payment.underpaid` - session closed with less than the required amount. Check `data.session.payment.amountReceived` vs `data.session.payment.amount`. Handle accordingly (refund, manual review, etc.). **Transaction events:** - `transaction.received` - payment detected on-chain but unconfirmed. Optionally notify the user that payment was detected. - `transaction.confirmed` - payment confirmed on the blockchain. **Webhook security:** - Verify the HMAC-SHA256 signature in the `x-coincircuit-signature` header using your webhook secret - Use the `x-coincircuit-delivery-id` header for idempotency (store processed delivery IDs and skip duplicates) ### 4. Track payment state Store a record linking the CoinCircuit session to your bot's user: - `telegramUserId` - `sessionReference` - the CoinCircuit payment session reference - `status` (`"pending"`, `"completed"`, `"expired"`) - Any use-case-specific fields (subscription expiry, product ID, etc.) This lets you look up payment status when a user asks, and lets your webhook handler find the right user to notify. ### 5. Recurring payments (if applicable) For subscription-based flows, create a new payment session each billing cycle: 1. **Before expiry:** Send the user a renewal payment link 2. **On expiry:** If not renewed, revoke access or downgrade 3. **On renewal payment:** Update the subscription period Store the `subscriptionPeriodEnd` in session metadata so your webhook handler knows the new expiry. ## Constraints - Session `amount` is a **string** in fiat, not a number (e.g. `"9.99"`) - Store the `telegramUserId` in both the session `metadata` and `customer.telegramId` for reconciliation - Always verify webhook signatures before taking action - Only act on `payment.completed`, not on partial or pending events - `successUrl` and `cancelUrl` must be HTTPS - Supported currencies: NGN, USD. Supported assets: BTC, ETH, USDT, USDC, SOL, BNB, TRX. Supported chains: bitcoin, ethereum, solana, bsc, tron, base, arbitrum. --- # x402 Payments | CoinCircuit Docs > Gate HTTP routes behind crypto payments using the x402 protocol. Source: https://coincircuit.io/docs/guides/x402/ Markdown: https://coincircuit.io/docs/guides/x402.md ## API reference - POST `/api/v1/x402/requirements`: [Build payment requirements](https://coincircuit.io/api-reference/#tag/x402/POST/api/v1/x402/requirements) - POST `/api/v1/x402/verify`: [Verify an x402 payment](https://coincircuit.io/api-reference/#tag/x402/POST/api/v1/x402/verify) - POST `/api/v1/x402/settle`: [Settle an x402 payment](https://coincircuit.io/api-reference/#tag/x402/POST/api/v1/x402/settle) x402 builds on the HTTP 402 status code to let AI agents and automated clients pay for API resources programmatically. It pairs a `402 Payment Required` response with gasless stablecoin payments, so a machine can pay $0.002 for an API call autonomously and settle it in the same request. CoinCircuit is the x402 facilitator. Your server states what a request costs, the agent signs a gasless payment, and CoinCircuit verifies it, covers gas, settles on-chain, and returns the transaction hash. The flow is stateless. ![x402 payment flow: an agent, your API, the CoinCircuit facilitator, and the blockchain](https://coincircuit.io/images/features/x402-flow.png) ## Key concepts **Resource server:** Your API. It returns the `402` with payment requirements, receives the signed payment, and calls CoinCircuit to settle before releasing the resource. **Facilitator:** CoinCircuit. It verifies and settles the signed payment and sponsors gas. Your server authenticates to it with your API key. **Payment requirements:** The terms in the `402` (scheme, network, amount, destination, token). CoinCircuit builds them for you from a chain, asset, and amount. **Gasless payment:** The agent signs an authorization to move funds from its wallet to your address. CoinCircuit submits it on-chain and pays the network fee. The agent needs only a wallet and a signing key. **Destination:** Funds land at the `payTo` you choose. Leave it unset and CoinCircuit uses your deposit address, so the payment credits your balance automatically. ## How the x402 flow works 1. The agent requests a protected resource from your API. 2. Your server builds requirements with `POST /api/v1/x402/requirements` and returns them in a `402 Payment Required`. 3. The agent reads the requirements and signs a gasless payment for the scheme its chain uses. 4. The agent retries the request with the signed payment. 5. Your server settles it with `POST /api/v1/x402/settle`. 6. CoinCircuit verifies the payment, covers gas, settles on-chain, and returns the transaction hash. 7. Your server releases the resource. ## Step-by-step integration ### 1. Agent requests your resource ```http GET /api/premium-data ``` ### 2. Build the payment requirements ```http POST https://api.coincircuit.io/api/v1/x402/requirements x-api-key: sk_live_your_key Content-Type: application/json { "chain": "base", "asset": "USDC", "amount": "0.10", "resource": "https://your-api.com/api/premium-data" } ``` The response is the ready-to-return 402 body. It carries a friendly summary plus the canonical `accepts` array a standard x402 client reads. ```json { "x402Version": 1, "chain": "base", "asset": "USDC", "amount": "0.10", "accepts": [ { "scheme": "exact", "network": "eip155:8453", "maxAmountRequired": "100000", "resource": "https://your-api.com/api/premium-data", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } ] } ``` ### 3. Return the 402 challenge Return the body with a `402` status. A standard x402 client reads `accepts[0]` and signs against it. ```json HTTP/1.1 402 Payment Required { "x402Version": 1, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "maxAmountRequired": "100000", "resource": "https://your-api.com/api/premium-data", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } ] } ``` ### 4. Receive the signed payment The agent signs a payment for the scheme its chain uses and sends back the canonical `paymentPayload`. ```json { "x402Version": 1, "scheme": "exact", "network": "eip155:8453", "payload": { "signature": "0xb91c5d2e8a4f0c7d3e6b9a1f2c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90a1b2c3d4e5f6a7b8c9d0e1f2a3b4c1b", "authorization": { "from": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b", "to": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "value": "100000", "validAfter": "0", "validBefore": "1774055094", "nonce": "0x9b2c4d6e8f0a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e0f2a4b6c8d0e1f3a5b7c" } } } ``` ### 5. Settle through CoinCircuit Forward the signed payload and the requirements you issued. ```http POST https://api.coincircuit.io/api/v1/x402/settle x-api-key: sk_live_your_key Content-Type: application/json { "x402Version": 1, "paymentPayload": { "x402Version": 1, "scheme": "exact", "network": "eip155:8453", "payload": { "signature": "0xb91c5d2e8a4f0c7d3e6b9a1f2c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90a1b2c3d4e5f6a7b8c9d0e1f2a3b4c1b", "authorization": { "from": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b", "to": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "value": "100000", "validAfter": "0", "validBefore": "1774055094", "nonce": "0x9b2c4d6e8f0a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e0f2a4b6c8d0e1f3a5b7c" } } }, "paymentRequirements": { "scheme": "exact", "network": "eip155:8453", "maxAmountRequired": "100000", "resource": "https://your-api.com/api/premium-data", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } } ``` A successful response returns the settled transaction. ```json { "success": true, "data": { "id": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7", "txHash": "0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3", "status": "confirmed", "amlCheck": "passed", "errorReason": null, "network": "eip155:8453", "chain": "base", "asset": "USDC", "payer": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "amount": "0.10", "fee": "0", "blockNumber": 21048765, "explorerUrl": "https://basescan.org/tx/0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3", "createdAt": "2026-06-25T21:09:02.000Z" } } ``` Deliver the resource once settlement succeeds, and persist the transaction hash for reconciliation. Each signed payment settles once. If the same payment is submitted again, settle returns `409 Conflict`; the chain never moves funds twice. ## Resource server example ```typescript app.get("/api/premium-data", async (_req, res) => { const requirements = await fetch("https://api.coincircuit.io/api/v1/x402/requirements", { method: "POST", headers: { "x-api-key": process.env.COINCIRCUIT_API_KEY!, "Content-Type": "application/json", }, body: JSON.stringify({ chain: "base", asset: "USDC", amount: "0.10", resource: "https://your-api.com/api/premium-data", }), }).then((response) => response.json()); return res.status(402).json(requirements.data); }); app.post("/api/premium-data/pay", async (req, res) => { const { paymentPayload, paymentRequirements } = req.body; const result = await fetch("https://api.coincircuit.io/api/v1/x402/settle", { method: "POST", headers: { "x-api-key": process.env.COINCIRCUIT_API_KEY!, "Content-Type": "application/json", }, body: JSON.stringify({ x402Version: 1, paymentPayload, paymentRequirements }), }).then((response) => response.json()); return res.json({ data: "premium resource", txHash: result.data.txHash }); }); ``` ## Pre-validate before settling Use `POST /api/v1/x402/verify` to dry-run a signed payment without touching the blockchain. It takes the same body as settle and runs the requirement and on-chain checks: destination, amount, timestamp, nonce replay, and sender balance. ## Discover supported networks `GET /api/v1/x402/supported` returns the chains and assets you can accept, and the Solana fee payer to use. ## Look up settled payments Every settlement is recorded against your account. List them, or fetch one by hash. Both return the same transaction object that settle returns. ```http GET https://api.coincircuit.io/api/v1/x402/transactions?chain=base&status=confirmed&page=1&size=20 x-api-key: sk_live_your_key ``` Filter with `chain`, `asset`, `status`, `search` (transaction hash or address), `startDate`, and `endDate`. Page with `page` and `size`. ```json { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7", "txHash": "0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3", "status": "confirmed", "amlCheck": "passed", "errorReason": null, "network": "eip155:8453", "chain": "base", "asset": "USDC", "payer": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "amount": "0.10", "fee": "0", "blockNumber": 21048765, "explorerUrl": "https://basescan.org/tx/0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3", "createdAt": "2026-06-25T21:09:02.000Z" } ], "meta": { "page": 1, "size": 20, "total": 1, "totalPages": 1 } } ``` Fetch a single payment by its transaction hash: ```http GET https://api.coincircuit.io/api/v1/x402/transactions/0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3 x-api-key: sk_live_your_key ``` ## Signing schemes The wire scheme is always `exact`. CoinCircuit selects the on-chain mechanism from the network and asset. | Asset | Networks | Mechanism | | :--- | :--- | :--- | | USDC | Base, Arbitrum, BSC, Solana | EIP-3009 (EVM), partial signing (Solana) | | USDT | Base, Arbitrum, BSC, Solana | Permit2 (EVM), partial signing (Solana) | **EVM (USDC, USDT):** the agent signs an EIP-712 authorization, using `extra.name` and `extra.version` from the requirements, and sends `{ signature, authorization }`. **Solana (USDC, USDT):** the agent builds an SPL token transfer, sets `extra.feePayer` from the requirements as the transaction fee payer, partially signs it, and sends `{ transaction }` as base64. CoinCircuit co-signs as fee payer at settlement. ## Why your server settles The agent signs the authorization; your backend settles it through CoinCircuit. The agent stays simple: just a wallet and a signing key. Your server stays in control: validate the request, settle, then release the resource only after confirmation. ## Use cases - Metered API endpoints billed per call - AI agent tool calls and MCP resource access - Paywalled datasets, reports, and one-time content - Compute, inference, storage, and SaaS actions priced per request --- # x402 API Monetization | CoinCircuit Docs > Charge AI agents per request over HTTP 402 with gasless stablecoin payments. Source: https://coincircuit.io/docs/guides/x402-api-monetization/ Markdown: https://coincircuit.io/docs/guides/x402-api-monetization.md Tags: x402, Agent Payments, Payments, Node.js Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io --- You are helping me add per-request crypto payments to my existing API using the x402 protocol and CoinCircuit as the facilitator. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_api_overview` in the CoinCircuit MCP for base URLs, auth method, and available features. - Call `get_endpoint` with method `post` and path `/api/v1/x402/requirements` for the payment requirements schema. - Call `get_endpoint` with method `post` and path `/api/v1/x402/settle` for the settlement schema. - Call `get_endpoint` with method `post` and path `/api/v1/x402/verify` for the pre-validation schema. - Call `get_endpoint` with method `get` and path `/api/v1/x402/supported` for the supported networks and assets. - Call `search_api` with query `x402` and type `endpoints` to find all x402 endpoints. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL (production):** `https://api.coincircuit.io` - **Base URL (sandbox):** `https://sandbox-api.coincircuit.io` - **Auth:** Pass your API key in the `x-api-key` header on every request. ## Project Context I have an API backend and I'm adding x402 payment gating so AI agents pay per request. The flow: 1. Agent hits a paid endpoint on my API. 2. My server asks CoinCircuit to build the payment requirements for the price. 3. My server returns a 402 with those requirements. 4. The agent signs a gasless payment and sends it back. 5. My server submits the signed payment to CoinCircuit, which settles it on-chain and covers gas. 6. My server delivers the resource once settlement confirms. The agent needs only a wallet and a signing key. ## What I Need You to Implement ### 1. Middleware: check for payment Create middleware that intercepts requests to paid endpoints. If the request has no payment, proceed to step 2 (build requirements and return 402). If it includes a signed payment, proceed to step 5 (settle). ### 2. Build the payment requirements When an agent hits a paid endpoint without payment: **Endpoint:** `POST /api/v1/x402/requirements` *(Call `get_endpoint` with method `post`, path `/api/v1/x402/requirements`, section `request` in the CoinCircuit MCP for the full request body.)* ```json { "chain": "base", "asset": "USDC", "amount": "0.10", "resource": "https://your-api.com/api/premium-data" } ``` **Response:** the ready-to-return 402 body, with a friendly summary and a canonical `accepts` array. `payTo` defaults to your deposit address, so the payment credits your balance. Pass your own `payTo` to settle elsewhere. *(Call `get_endpoint` with method `post`, path `/api/v1/x402/requirements`, section `success` in the CoinCircuit MCP for the full response.)* ### 3. Return the 402 response Return the body with a 402 status. A standard x402 client reads `accepts[0]` and signs against it. ### 4. Agent signs the payment (client-side reference) The wire scheme is `exact`. The agent signs for the mechanism its chain uses and returns the canonical `paymentPayload`: - **USDC on EVM:** an EIP-712 `TransferWithAuthorization` (EIP-3009), returned as `{ signature, authorization }`. - **USDT on EVM:** a Permit2 permit, returned as `{ signature, authorization }`. - **USDC or USDT on Solana:** an SPL token transfer with `extra.feePayer` set as the transaction fee payer, partially signed, returned as `{ transaction }` (base64). The agent sends the `paymentPayload` back to your server. ### 5. Pre-validate the payment (optional but recommended) Before settling, dry-run the payment: **Endpoint:** `POST /api/v1/x402/verify` *(Call `get_endpoint` with method `post`, path `/api/v1/x402/verify` in the CoinCircuit MCP for the full schema.)* It takes the same body as settle and returns the per-check result, so you can catch insufficient balance, expired authorizations, and invalid signatures before settling. ### 6. Settle the payment on-chain **Endpoint:** `POST /api/v1/x402/settle` *(Call `get_endpoint` with method `post`, path `/api/v1/x402/settle` in the CoinCircuit MCP for the full request/response schema.)* Send `{ x402Version, paymentPayload, paymentRequirements }`, the signed payload plus the requirements you issued. CoinCircuit verifies the payment, submits the transaction on-chain, covers gas, and returns the transaction hash and confirmation. ### 7. Deliver the resource Once the settle response confirms success, return the requested data to the agent with the transaction hash as a receipt. ### Integration Flow Summary ``` Agent -> GET /api/premium-data Server -> CoinCircuit: POST /api/v1/x402/requirements Server -> Agent: 402 (accepts: payment requirements) Agent -> Signs the payment (exact scheme) Agent -> Server: POST /api/premium-data/pay (signed paymentPayload) Server -> CoinCircuit: POST /api/v1/x402/verify (optional) Server -> CoinCircuit: POST /api/v1/x402/settle Server -> Agent: 200 (resource + tx receipt) ``` ### Supported Chains and Assets | Asset | Networks | Mechanism | |-------|----------|-----------| | USDC | Base, Arbitrum, BSC, Solana | EIP-3009 (EVM), partial signing (Solana) | | USDT | Base, Arbitrum, BSC, Solana | Permit2 (EVM), partial signing (Solana) | ## Constraints - Forward the same `paymentRequirements` you issued into the settle call alongside the signed `paymentPayload`. CoinCircuit checks the payment matches them. - The agent signs the authorization; your server settles it. This lets you validate the request and release the resource only after settlement confirms. - `amount` is a decimal string in asset units (e.g. `"0.10"` USDC). - Use the verify endpoint first in production to catch bad signatures before spending gas. - Solana payments expire in ~60 seconds based on the blockhash. Build the requirements close to when the agent will sign. - For Permit2 (USDT), the agent does a one-time on-chain approval of the Permit2 contract (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) for the token. - EVM networks offer sub-second block times and gas costs under a cent. Solana settles in under a second with fees below $0.001. --- # API Reference | CoinCircuit > Complete API reference for CoinCircuit: endpoints, request/response schemas, authentication, webhooks, refunds, and settlements. Build with confidence. Source: https://coincircuit.io/api-reference/ Markdown: https://coincircuit.io/api-reference.md # CoinCircuit API Reference CoinCircuit REST API, full endpoint reference. ## Miscellaneous - **GET** `/api/v1/blockchain/assets`: Retrieve supported blockchains and assets Returns the full detailed list of supported blockchains and assets. - **GET** `/api/v1/blockchain/confirmations`: Retrieve confirmation requirements Returns the number of confirmations required for transactions to be considered final on different blockchains. - **GET** `/api/v1/blockchain/gas-fees`: Retrieve gas fees Returns gas fees for all supported blockchains. All fee values are returned in the native token/asset value. ## Balance - **GET** `/api/v1/balance`: Retrieve balances Returns all balances - **GET** `/api/v1/balance/transactions`: List balance transactions Returns your balance transactions. - **GET** `/api/v1/balance/transactions/{id}`: Get a balance transaction by id ## Swap - **GET** `/api/v1/swap/rates`: List swap rates - **GET** `/api/v1/swap/estimate`: Estimate swap amount - **POST** `/api/v1/swap/quotation`: Create a swap quotation Creates a swap quotation that locks the rate for 30 seconds. Execute the quotation before it expires. - **GET** `/api/v1/swap/quotation/{quotationId}`: Get swap quotation by ID - **POST** `/api/v1/swap/execute/{quotationId}`: Execute swap quotation - **GET** `/api/v1/swaps`: List swaps - **GET** `/api/v1/swaps/{id}`: Get swap details by ID ## Payout Recipients - **POST** `/api/v1/recipients`: Create payout recipient Adds a payout recipient. Set type to crypto\_address, ngn\_bank\_account, kes\_mobile\_money (Kenya) or ghs\_mobile\_money (Ghana) and supply the matching details. Bank accounts are verified and must match your name or business name. If a matching recipient already exists, the existing one is returned instead of creating a duplicate. - **GET** `/api/v1/recipients`: List payout recipients Returns your saved payout recipients. Filter by type to return a single rail, or omit type to return all types. - **POST** `/api/v1/recipients/validate`: Validate recipient details Preflight check before creating a recipient. Crypto validates the address format. Bank resolves the account holder name through the provider. Mobile money resolves the corridor and provider for the details. - **GET** `/api/v1/recipients/banks`: List supported banks Banks available for bank account recipients. Nigeria (ng) only for now. - **GET** `/api/v1/recipients/chains`: List supported payout chains Returns the chains and assets available for crypto\_address recipients, keyed by chain. - **GET** `/api/v1/recipients/{id}`: Retrieve payout recipient Returns the payout recipient for the given ID. - **DELETE** `/api/v1/recipients/{id}`: Delete payout recipient Deletes the payout recipient. ## Refunds - **POST** `/api/v1/refunds/session/{sessionReference}`: Process session refund Refunds the money received in a payment session back to the customer. - **POST** `/api/v1/refunds/invoice/{invoiceReference}`: Process invoice refund Refunds the money paid for an invoice back to the customer. - **GET** `/api/v1/refunds`: List refunds Returns all refunds. - **GET** `/api/v1/refunds/estimate/{reference}`: Estimate refund Get refund estimation including fees and amounts. Specify entity type (session/invoice) via query parameter. - **GET** `/api/v1/refunds/{id}`: Retrieve refund Returns the refund for the given ID. ## Payouts - **POST** `/api/v1/payouts`: Initiate payout Initiates a payout to a recipient. Requests authenticated with an API key never need a one-time code. Dashboard requests need a one-time code unless the recipient is trusted. - **GET** `/api/v1/payouts`: List payouts Returns all payouts. - **POST** `/api/v1/payouts/quote`: Quote a payout Returns the fee and conversion for a payout the recipient receives in a different currency from the balance that pays for it, e.g. KES or ETH. Call it before creating the payout to show the cost. - **POST** `/api/v1/payouts/cross-border/quote`: Quote a cross-border payout Deprecated: use POST /payouts/quote. Returns the fee and conversion for a cross-border payout, priced by the amount to pay from a balance (sourceAmount). Cross-border payouts are available to verified businesses. - **GET** `/api/v1/payouts/{id}`: Retrieve payout Returns the payout for the given ID. - **GET** `/api/v1/payouts/fees`: Retrieve all payout fees Returns fiat, cross-border, and crypto payout fees across every supported currency, corridor, chain, and asset. ## Deposits - **POST** `/api/v1/deposits/accounts`: Create a deposit account Creates a deposit account. Omit customerId to create a parent account. A holder has one deposit account, so repeat calls return the existing account. - **GET** `/api/v1/deposits/accounts`: List deposit accounts Lists your deposit accounts. - **PATCH** `/api/v1/deposits/accounts/{id}`: Update a deposit account Changes the settlement currency of a customer-scoped deposit account. Deposits already in flight keep the currency they were credited in. The merchant parent account is always \`default\`. - **GET** `/api/v1/deposits/accounts/{id}`: Retrieve a deposit account Retrieves a deposit account and its identities. - **POST** `/api/v1/deposits/accounts/{id}/identities`: Issue a deposit identity Issues a pay-in identity into a deposit account: a static crypto deposit address or an NGN virtual account. - **GET** `/api/v1/deposits/accounts/parent`: Retrieve parent deposit account Retrieves the merchant parent deposit account. - **GET** `/api/v1/deposits/accounts/customer/{customerId}`: Retrieve a customer's deposit account Retrieves the deposit account for a customer. - **GET** `/api/v1/deposits`: List deposits Lists your inbound deposits (crypto and fiat). - **GET** `/api/v1/deposits/{id}`: Retrieve a deposit Retrieves a single deposit. ## Customers - **POST** `/api/v1/customers`: Create customer Creates a new customer. If a customer with the same email, phone, or telegram ID already exists, it will be updated instead. - **GET** `/api/v1/customers`: List customers Returns all customers. - **PATCH** `/api/v1/customers/{id}`: Update customer Updates the customer. - **GET** `/api/v1/customers/{id}`: Retrieve customer Returns the customer for the given ID. ## Invoices - **POST** `/api/v1/invoices`: Create invoice Creates an invoice for a product/service. - **GET** `/api/v1/invoices`: List invoices Returns all invoices. - **GET** `/api/v1/invoices/reference/{reference}`: Retrieve invoice by reference Returns the invoice for the given reference. ## x402 - **POST** `/api/v1/x402/requirements`: Build x402 payment requirements Build the payment requirements to return to a paying agent. - **POST** `/api/v1/x402/verify`: Verify an x402 payment Validate a signed payment against its requirements without settling. - **POST** `/api/v1/x402/settle`: Settle an x402 payment Submit a signed payment on-chain and return the settlement receipt. - **GET** `/api/v1/x402/supported`: List supported x402 networks and assets - **GET** `/api/v1/x402/transactions`: List x402 transactions List settled x402 payments for your account, newest first. - **GET** `/api/v1/x402/transactions/{txHash}`: Get an x402 transaction Fetch a settled x402 payment by transaction hash. ## Payments - **POST** `/api/v1/payments`: Create payment session Creates a new payment session (payment link) to receive payments. You can set the asset and chain together, set one now and the other later, or leave both unset. A deposit address is created immediately only when the session already has the asset, chain, and customer details. - **GET** `/api/v1/payments`: List payment sessions Returns all Payment Sessions. - **POST** `/api/v1/payments/{reference}/address`: Generate deposit address Generates a deposit address for the session. If the session already has an asset or chain assigned, those values cannot be overridden. Any missing asset or chain must be provided before the address can be created. If the session does not already have a customer, include customer details (email, and optionally firstName, lastName, phone). If the session already has a customer, the customer field is ignored. - **POST** `/api/v1/payments/{reference}/pay-with-exchange`: Create exchange payment link Returns a link to pay the session from an exchange wallet, e.g. Binance. Generate a deposit address first. - **GET** `/api/v1/payments/reference/{reference}`: Retrieve payment session by reference Returns the session for the given reference. - **GET** `/api/v1/payments/estimate`: Calculate crypto amount for session Calculate the required crypto amount for a session based on selected asset and chain without locking the rate. ## Payment Pages - **POST** `/api/v1/payments/pages`: Create payment page Creates a new payment page. - **GET** `/api/v1/payments/pages`: List payment pages Returns all payment pages. - **GET** `/api/v1/payments/pages/{reference}/sessions`: Retrieve payment page by reference Returns the payment page for the given reference. - **PATCH** `/api/v1/payments/pages/{id}`: Update payment page Updates the payment page. - **DELETE** `/api/v1/payments/pages/{id}`: Delete payment page Deletes the payment page. ## Transactions - **GET** `/api/v1/transactions`: List transactions Returns all Payment Sessions Blockchain transactions. - **GET** `/api/v1/transactions/{txHash}`: Retrieve transaction Returns the transaction for the given hash. ## Settlements - **GET** `/api/v1/settlements`: List settlements - **GET** `/api/v1/settlements/{reference}`: Retrieve settlement data --- # Pricing | Low Fees from 0.5% | CoinCircuit > Simple, transparent crypto payment fees. Payment links at 1%, account top-ups at 0.5%, invoices at 1%. No setup fees. Source: https://coincircuit.io/pricing/ Markdown: https://coincircuit.io/pricing.md Pricing # Simple, Honest Pricing No setup fees, no hidden costs. Plans Transaction Fee 1 % Instant settlement No setup fees No monthly dues Bank-grade security 24/7 Priority support [Get started](https://dashboard.coincircuit.io/signup) Transaction Customer Pays ₦10,000.00 Fee (1%) \-₦100.00 You Receive ₦9,900.00 Settled Instantly ### Enterprise Custom pricing for high-volume businesses. - Volume-based discounts - Fixed fee per transaction - Custom settlement flows - Dedicated support & SLAs [Contact sales](https://coincircuit.io/contact/) Detailed pricing ### Accept crypto payments with transparent pricing. Transactions Static deposit address Direct transfers to dedicated wallets. 0.5% Payment links & invoices Shareable checkout, trackable invoices. 1.0% x402 agent transactions Machine-to-machine settlement submission. Free Refunds Refund processing Reverse a settled payment back to the customer. 1.5 USDT Crypto payouts Tron (TRC-20) Ethereum 1.0 USDT BNB Smart Chain 0.5 USDT Solana Base Bank transfer NGN bank transfer Settles to any Nigerian bank instantly. ₦200 ### Ready to start accepting crypto? Join businesses using CoinCircuit to accept crypto payments at scale. [Create Free Account](https://dashboard.coincircuit.io/signup) [Talk to Sales](https://coincircuit.io/contact/) --- # Crypto Payment Features | CoinCircuit > Smart routing, hosted checkout, automated settlements, and AI-powered analytics. Everything you need to accept crypto payments at scale. Source: https://coincircuit.io/features/ Markdown: https://coincircuit.io/features.md Platform Overview # Everything You Need Built for reliability, scale and simplicity. Designed for modern finance teams. Payments ### Crypto Checkout Accept crypto payments with branded checkout pages or payment links created straight from the API. 200.00 USDT $200.00 Network BSC (BEP-20) *QR Code* BSC (BEP-20) address 0xb50837139CD9339d114fd170391c3061c7b292Ee Expires In 09:45 Confirmations 0 from 6 Conversion ### On & Off Ramp Instantly swap between crypto and fiat currencies at transparent rates. *On & Off Ramp* Settlement ### Local Currency Support Price in local currencies like NGN, GHS, or ZAR and receive payouts directly in your preferred currency. *Local Currency Support* Billing ### Invoices Bill customers in crypto with recurring invoices and subscriptions. Create, send, and track every invoice. *Invoices* Banking ### Deposit Accounts Issue unique dedicated NGN virtual accounts and static deposit addresses across multiple blockchains for your users. *Deposit Accounts* Compliance ### AML Screening Screen customers and transactions against OFAC and other sanctions lists, with ongoing AML monitoring. *AML Screening* Disbursement ### Payouts Send stablecoin and fiat payouts, to wallets or bank accounts, in a single API call. *Payouts* In Person ### In-Store POS Accept crypto payments at physical locations with our point-of-sale terminal. *In-Store POS* ### Pay with Exchange Direct integrations with major exchanges. Customers can pay straight from their exchange account. *Pay with Exchange* AI Agents ### Agentic Payments Accept payments from AI agents with x402. Machine-to-machine settlement, directly on the blockchain. *Agentic Payments* Intelligence ### AI Assistant A business assistant that analyzes your payment and business data, surfaces insights, and helps you get things done. *AI Assistant* Automation ### AI Chat Bots Create payment links and track payments directly in Telegram or WhatsApp, 24/7. *AI Chat Bots* Spending ### Crypto Card Issue virtual and physical stablecoin-funded cards for your customers to spend directly from their balance. *Crypto Card* ## Everything In One Unified View Track revenue, manage routing, and analyze performance from a single dashboard. *CoinCircuit analytics dashboard* ### Enterprise Security Safeguards, audited processes, and continuous monitoring. AES-256-GCM Encryption for all data at rest. TLS 1.3 Transport security with forward secrecy. MFA Enforcement Mandatory multi-factor authentication. HMAC Signatures Cryptographically signed API requests. ### Advanced Capabilities Powerful tools designed to help you scale operations and gain better visibility into your business. AI Operations Auto-remediation and alerts. Global Coverage Accept customers from 180+ countries. Team Management Granular roles and permissions. Webhooks Real-time event notifications. Optimized Routing Lower fees, higher success. Deep Reporting Customizable analytics. ### Ready to upgrade your payments? Start accepting payments today with reliable, secure infrastructure. [Create free account](https://coincircuit.io/features/) [Talk to sales](https://coincircuit.io/contact/) --- # Use Cases | CoinCircuit > How businesses use CoinCircuit: cross-border payments, ecommerce checkout, iGaming deposits and payouts, marketplace disbursement, white label fintech, agentic payments and subscription billing. Source: https://coincircuit.io/use-cases/ Markdown: https://coincircuit.io/use-cases.md # Use Cases Businesses use CoinCircuit to power their crypto payment infrastructure end to end, accepting payments, settling and paying out across multiple blockchains. Here is what that looks like across seven kinds of company. [See pricing›](https://coincircuit.io/pricing/) B2B settlement ## Cross-Border Payments Accept stablecoin payments from customers anywhere in the world and settle directly to local bank accounts or crypto wallets. - Settle in local currency or stablecoins - Global payout corridors - 10+ blockchains *Two brushed metal arches over a dotted world map, with a USDT coin crossing between them on a trail of light* Online and in store ## Ecommerce & Retail Let customers pay with crypto through your website, ecommerce store or physical location using hosted checkout, plugins or QR payments. - Hosted checkout - WooCommerce & OpenCart - QR and POS *A brushed metal shopping bag lit from within, with USDT, USDC and Bitcoin coins falling into it* High frequency ## iGaming Enable players to deposit with crypto in seconds and withdraw winnings just as quickly. - Confirmations from 5s - Zero chargebacks - Partial payments *Machined metal dice and a roulette wheel tumbling beside USDT and Bitcoin coins* Disburse at scale ## Marketplaces & Mass Payouts Send payouts to merchants, creators, freelancers and contractors through crypto or local bank transfers. - Bulk disbursement - Wallet or bank - Global coverage *A large USDT coin fanning light conduits down to USDC, Ghana, Nigeria, USDT and euro coins* White label ## Remittance & Fintech Platforms Offer crypto payment services inside your own product while CoinCircuit manages the blockchain infrastructure behind the scenes. - Your branding - Full API and SDKs - Role-based team access *A machined silver bank facade with gradient light pouring between its columns, beside a USDC coin* Agentic payments ## AI Agents & Autonomous Commerce Allow AI agents to make and receive payments without manual approval, using infrastructure built for autonomous commerce. - x402 protocol - MCP server - Automated payments *A glowing geodesic cage around a blue Base disc, releasing a USDC coin* Recurring revenue ## SaaS & Subscriptions Create invoices, share payment links and manage subscription payments from one dashboard. - Invoices - Payment links - Refunds *A curling paper receipt lit by gradient light, with an Ethereum coin resting against it* ## Multiple Blockchains Supported Bitcoin BNB Chain Solana Ethereum Tron Litecoin Polygon Avalanche ### Find your use case? Create an account and take your first payment today, or talk to us about what you are building. [Get Started Free](https://dashboard.coincircuit.io/signup) [Talk to Sales](https://coincircuit.io/contact/) --- # Accept Crypto Payments for Business | CoinCircuit > The fastest way for African and global businesses to accept Bitcoin, USDT, and 50+ cryptocurrencies. Zero chargebacks, instant settlements, free integration. Source: https://coincircuit.io/business/ Markdown: https://coincircuit.io/business.md Accept Crypto Payments # Crypto Payments for Your Business Accept Bitcoin, USDT, ETH and more. ## Flexible Ways to Accept Crypto Choose the integration that fits your business model, from physical stores to automated AI agents. Physical ### Accept In-Store Show a QR code at checkout. Customers pay in crypto, and you get paid in local currency like NGN, instantly. API ### Accept Online Integrate our API into your website or app. Full control over the checkout flow and branding. AI ### AI Agents Accept payments from AI agents automatically. No human checkout, no card required. Accept Online ## Integrate in Minutes Our developer-first API lets you create payment sessions and handle crypto transactions with just a few lines of code. No wallet management or blockchain node infrastructure required. \>\_ payment.ts ``` TypeScript1import { CoinCircuit } from "@coincircuit/sdk";23const apiKey = process.env.KEY;4const coincircuit = new CoinCircuit({ apiKey });56const session = await coincircuit.createPayment({7 amount: 100,8 currency: "USD",9 chain: "base",10 asset: "USDC",11 customer: { email: "customer@example.com" }12}); ``` TS 5.0 *Coincircuit* CoinCircuit [Sign Up](https://dashboard.coincircuit.io/signup) # Select Currency ₦30,000 Select asset, then choose network You pay network fee Expires In 01:00:00 *USDT* USDT *bsc* BSC Proceed to Payment Step 1 of 3 *In-Store Crypto Payment* Accept In-Store ## QR Code or POS, You Choose Accept crypto at the counter with a QR code on any screen, or through our dedicated POS terminal. Customers scan, pay, and you receive local currency instantly. #### Instant Conversion Crypto is converted to NGN, GHS, or ZAR the moment the payment confirms. #### Settled to Your Bank Funds land in your bank account within seconds, not days. #### No Special Hardware Use any phone, tablet, or our POS terminal. No proprietary equipment required. 1 #### Agent Hits Your API The agent makes a request to your endpoint. Your server returns a 402 with payment details. 2 #### Agent Signs Payment The agent signs a USDC or USDT authorization with its own key and sends the payload back. 3 #### CoinCircuit Settles Your server submits the signed payload. CoinCircuit settles on-chain and you receive funds. The Agentic Economy ## Accept Payments from AI Agents AI agents are already buying things. They purchase API access, hire services, and execute transactions without a human in the loop. If you sell anything online, agents are becoming a real customer segment. CoinCircuit lets agents pay you in USDC or USDT and settle to your account in seconds. No card required on their end, no new setup on yours. ### Scale Your Business with Crypto Join modern merchants who are already accepting global payments with CoinCircuit. No setup fees, no monthly costs. [Get Started Free](https://dashboard.coincircuit.io/signup) [Contact Sales](https://coincircuit.io/contact/) --- # Crypto Invoicing | Professional Billing | CoinCircuit > Create and send trackable crypto payment invoices via API or dashboard. Instant confirmation and automatic reconciliation. Source: https://coincircuit.io/products/invoices/ Markdown: https://coincircuit.io/products/invoices.md Invoicing # Crypto Invoice: Secure & Global Payments Send trackable crypto payment invoices to customers anywhere in the world. [Get Started](https://dashboard.coincircuit.io/signup) [Sign In](https://coincircuit.io/docs/) ## Everything you need to bill in crypto Create professional invoices from your dashboard or via API. Set amounts in fiat, let customers pay in any supported cryptocurrency. Create invoices via API or dashboard Automatic expiry and reminders Multi-currency: USDT, USDC, BTC, ETH and more Webhook notifications on payment CSV export for accounting Partial payment support *CoinCircuit crypto invoice* ## Why Choose CoinCircuit? Send trackable crypto invoices to customers anywhere. ### Instant Confirmation Know the moment an invoice is paid. Payment status updates in real time. ### Global Reach Accept crypto payments from any country and settle in stablecoins or local currency. ### Trackable Status See when a customer receives, views, and pays every invoice you send. ### Shareable Links Every invoice comes with a link you can share by email, chat, or your website. ## Multiple Blockchains Supported Bitcoin BNB Chain Solana Ethereum Tron Litecoin Polygon Avalanche ### Start Invoicing in Crypto Today Create your first invoice in minutes. No setup fees. [Get Started Free](https://dashboard.coincircuit.io/signup) [View API Docs](https://coincircuit.io/docs/) --- # Payment Links | No-Code Crypto Payments | CoinCircuit > Generate shareable crypto payment links with no code. Share via Telegram, WhatsApp, email, or SMS. Accept 50+ cryptocurrencies. Source: https://coincircuit.io/products/payment-links/ Markdown: https://coincircuit.io/products/payment-links.md Payment Links # Crypto Payment Links: Share a Link, Get Paid Create a payment link in a few clicks, share it with your customer, and track the payment in real time. [Create a Payment Link](https://dashboard.coincircuit.io/signup) [Sign In](https://dashboard.coincircuit.io) ## One link. Share everywhere. Set the amount and accepted currencies. CoinCircuit generates a unique payment link you can send to anyone. Customers pick their preferred crypto, pay from any wallet, and you get notified the moment funds arrive. Telegram WhatsApp Email SMS Website QR Code *Coincircuit* CoinCircuit [Sign Up](https://dashboard.coincircuit.io/signup) # Select Currency ₦30,000.00 Select asset, then choose network You pay network fee Expires In 00:14:56 *USDT* USDT *bsc* BSC Proceed to Payment Step 1 of 3 Underpaid Coverage ## Never Reject a Payment Network fees and wallet rounding can cause a customer's transfer to land slightly below the invoiced amount. Without Underpaid Coverage, that payment gets rejected and you lose the sale. Set your own underpayment threshold and CoinCircuit marks the invoice as paid when the shortfall falls within your limit. Steady cash flow, no rejected payments, no refund requests. Configurable threshold Threshold 10% Invoice amount $100.00 Customer paid $91.50 Shortfall \-$8.50 (8.5%) Status Accepted ## How to Generate a Payment Link Three ways to create a link. Pick whichever fits your workflow. ### Dashboard Open the Payment Links section, enter the amount, choose accepted currencies, and generate a link in a few clicks. ### API Create a link with a single API call. The response returns a shareable link you can send straight to your customer. ### AI Agents Connected AI agents can create and share payment links on their own through the Model Context Protocol. ## Built for Any Business Just a link and a customer. ### No Website Needed Freelancers, small shops, and service providers collect crypto payments with just a link. No storefront required. ### Share Anywhere Send your payment link over Telegram, WhatsApp, SMS, email, or paste it on social media. Works on every platform. ### Real-Time Notifications Get Telegram or WhatsApp alerts the moment a customer pays. Track every link's status from your account. ## Multiple Blockchains Supported Bitcoin BNB Chain Solana Ethereum Tron Litecoin Polygon Avalanche ### Start Collecting Payments Today Create your first payment link in under 60 seconds. [Get Started Free](https://dashboard.coincircuit.io/signup) [Contact Sales](https://coincircuit.io/contact/) --- # Crypto Payouts API | Bulk Payouts | CoinCircuit > Automate bulk crypto payouts to any address. Send USDT, USDC, BTC, and more programmatically via a single REST API call. Source: https://coincircuit.io/products/payouts/ Markdown: https://coincircuit.io/products/payouts.md Payouts API # Transfer USDC With The Payout API Send USDT and USDC to any wallet address across 10 blockchains. One API call, processed instantly. [Get Started Free](https://dashboard.coincircuit.io/signup) [View API Docs](https://coincircuit.io/docs/) ## How Payouts Work Three steps from API call to confirmed transfer. 01 ### Create a Payout Call the payouts API with the recipient address, amount, asset, and blockchain. CoinCircuit validates and queues the transfer. 02 ### Transfer Processed CoinCircuit validates the address and submits the transaction on the target blockchain. Transfers process instantly. 03 ### Webhook Confirmation Receive a signed webhook event once the payout confirms on the blockchain. ## One Call to Send Anywhere Specify the recipient, amount, asset, and chain. CoinCircuit handles routing and confirmation. payout.ts ``` 1import { CoinCircuit } from "@coincircuit";23const cc = new CoinCircuit({ apiKey: process.env.KEY });45const payout = await cc.payouts.create({6 recipient: "0xRecipientAddress...",7 amount: "50.00",8 currency: "USD",9 asset: "USDT",10 chain: "base",11}); ``` #### Sub-second Settlement Payouts on Solana and Base settle in under 1 second. #### 10 Blockchains Bitcoin, Ethereum, Solana, BSC, Tron, Base, Arbitrum, Polygon, and more. #### Single API Call One endpoint handles every blockchain and asset. #### Batch Payouts Pay multiple recipients in a single API call. ## Payout Fees Flat per-transfer fees. No hidden costs. Crypto On-chain Tron (TRC-20) 1.5 USDT Ethereum 1.0 USDT BNB Smart Chain 0.5 USDT Solana Base Bank Transfer Fiat ₦200 per transfer to Nigerian banks All Nigerian banks supported Processed instantly ## Multiple Blockchains Supported Bitcoin BNB Chain Tron Litecoin Polygon Avalanche ### Start Sending Payouts Today Integrate once. Send to any address on any supported blockchain. --- # QR Code Crypto Payments | In-Person | CoinCircuit > Accept in-person crypto payments with a dynamic or static QR code. Zero hardware required, instant bank settlements. Source: https://coincircuit.io/products/qr-payments/ Markdown: https://coincircuit.io/products/qr-payments.md QR Payments # Accept Crypto In Any Store Print a static QR code that links to your payment page. Customers scan, pick their currency, and pay from any wallet. No extra hardware needed. [Generate Your QR Code](https://dashboard.coincircuit.io/signup) [Talk to Sales](https://coincircuit.io/contact/) *In-Store Crypto Payment* ## Built for Every In-Person Business No industry-specific setup. If you can display a QR code, you can accept crypto. *QR code payment displayed at a restaurant table for in-person crypto checkout* ### Restaurants & Cafes Display a QR code at the table or counter. Customers scan and pay, and the money arrives in seconds. *QR code payment displayed at a retail shop counter* ### Retail Shops Print QR codes on receipts or signage, or generate one per sale from your point of sale. *QR code payment shown at a hotel front desk during check-in* ### Hotels & Hospitality Accept crypto at check-in or checkout. Ideal for international guests who prefer not to pay by card. *QR code payment at a supermarket checkout lane* ### Supermarkets Put a QR code at every checkout lane. Customers scan and pay while their groceries are bagged. 01 / 04 ## How It Works 01 ### Create a Payment Page Set up a payment page with the amount and accepted currencies. CoinCircuit generates a static QR code that links to it. 02 ### Customer Scans & Pays The customer scans the QR code and lands on your payment page. They pick a currency, pay from any wallet, and confirm. 03 ### Instant Settlement Payment confirms on the blockchain in seconds. Your dashboard updates and you receive your settlement. ## Why Choose CoinCircuit? Accept crypto at the counter with zero new hardware. ### Instant In-Store Payments Customers scan, confirm, and pay in seconds, right at the counter. ### Any Device Support Show your QR code on a phone, tablet, or screen, or print it and place it at the counter. ### Global Customers Customers from anywhere can pay you, whatever currency they hold. ### No Hardware Needed No new terminals to buy. Works with the devices you already have. ## Multiple Blockchains Supported Bitcoin BNB Chain Solana Ethereum Tron Litecoin Polygon Avalanche ### Start Accepting Crypto In-Store Today Generate your first QR code in seconds. No hardware. No setup fees. [Get Started Free](https://dashboard.coincircuit.io/signup) [Contact Sales](https://coincircuit.io/contact/) --- # Crypto POS Terminals | In-Store | CoinCircuit > Turn any device into a crypto point of sale. Create a terminal, connect your phone or tablet, and take crypto payments in your store. Source: https://coincircuit.io/products/pos/ Markdown: https://coincircuit.io/products/pos.md In-Store POS # Turn Any Device Into A Crypto POS Create a terminal in your dashboard, connect it to your phone or tablet, and take crypto payments in your store. Every payment shows up in your dashboard as it happens. [Create a Terminal](https://dashboard.coincircuit.io/signup) [Talk to Sales](https://coincircuit.io/contact/) ## How It Works 01 ### Create a Terminal Add a terminal in your dashboard and link it to a payment page. You can create one for each device or location. 02 ### Connect Your Device Generate a setup code, then enter it with your email on the phone or tablet you want to use. The device is connected right away. 03 ### Take Payments Enter the amount and show the customer the payment screen. They pay in crypto and the money lands in your balance. ## Built for In-Person Business If you take payments face to face, this works for you. ### Retail Stores Take crypto payments in your shop without buying any new hardware. ### Restaurants & Cafes Take payments at the counter or at the table from any phone or tablet. ### Salons & Services Charge for appointments and walk-ins on the device you already use every day. ### Pop-Ups & Events Set up a terminal on a spare phone for the weekend, then remove it when the event ends. ## Why Choose CoinCircuit? No hardware to buy. Everything is managed from your dashboard. ### Works On Any Device Use the phones and tablets you already own. There is no special hardware to buy. ### Easy Setup Connect a device with a setup code in under a minute. Remove old devices at any time. ### Every Location Covered Create a terminal per store, device, or staff member, and see where each payment came from. ### Live In Your Dashboard Every payment appears in your dashboard the moment it happens, across all your terminals. ## Multiple Blockchains Supported Bitcoin BNB Chain Solana Ethereum Tron Litecoin Polygon Avalanche ### Accept Crypto in Your Store Create a terminal, connect your device, and take your first payment today. [Get Started Free](https://dashboard.coincircuit.io/signup) [Contact Sales](https://coincircuit.io/contact/) --- # White-Label Crypto Payments | Your Brand | CoinCircuit > Integrate a fully branded crypto payment gateway. Your logo, your domain, powered by CoinCircuit infrastructure. Source: https://coincircuit.io/products/whitelabel/ Markdown: https://coincircuit.io/products/whitelabel.md White Label # Your Brand. Our Infrastructure. Deploy a fully branded crypto payment gateway. Your logo, domain, and customer experience, powered by CoinCircuit's infrastructure. [Talk to Sales](https://coincircuit.io/contact/) [View Docs](https://coincircuit.io/docs/) ## Full White-Label Package Everything you need to launch a branded crypto payment gateway. Custom logo, colors, and checkout styling Custom domain (pay.yourbrand.com) Remove all CoinCircuit branding Dedicated API key and sandbox Co-branded settlement reports Priority support and account manager [Contact Sales](https://coincircuit.io/contact/) ## Why Choose CoinCircuit? Reliable infrastructure behind your brand. ### Full Brand Control Use your own logo, colors, and domain. A completely seamless branded experience. ### Global Payments Accept 50+ assets across 10+ blockchains. All under your brand with fast settlement. ### Security Built In Standard encryption and MFA included. Secure HMAC-signed API requests by default. ### Simple Integration Integrate our REST API in hours. Full webhook, sandbox, and SDK support available. ### Launch Your Branded Gateway Contact our sales team to discuss your white-label deployment. --- # Crypto Payments in Nigeria | Settle to NGN | CoinCircuit > Accept Bitcoin, USDT, and stablecoins in Nigeria. Settle directly to your NGN bank account with low fees and instant confirmation. Source: https://coincircuit.io/nigeria/ Markdown: https://coincircuit.io/nigeria.md Nigeria # Crypto Payments in Nigeria Accept Bitcoin, USDT, and stablecoins. Settle to your NGN bank account. [Start Accepting Crypto](https://dashboard.coincircuit.io/signup) [Talk to Sales](https://coincircuit.io/contact/) $0B Crypto volume in Nigeria SEC Nigeria, 2024 0% Merchants saw revenue growth After adding crypto Flat transaction fee No hidden costs <0min NGN settlement time To your bank account ## Accept Crypto, Receive Naira Your customers pay in crypto. You get NGN in your bank account. Three steps. 01 ### Customer Selects Crypto They pick USDT, Bitcoin, or any supported token at checkout. Works with any wallet app they already use. 02 ### Payment Confirms On-Chain CoinCircuit monitors the blockchain and confirms the transaction. No manual verification needed. 03 ### NGN Hits Your Account We convert and settle Naira directly to your bank account within minutes. ## Why Nigerian Merchants Accept Crypto Cross-border card payments cost 3-5% in fees and take days to settle. Crypto payments cost 1% and settle in minutes. Nigerian merchants who added crypto saw 88% revenue growth. #### Lower Fees Than Cards Flat 1% fee vs 3-5% for cards. Keep more revenue from every global transaction. #### Minutes, Not Days Rapid NGN bank settlement in under 2 minutes. No more waiting for your funds. #### Sell to Anyone, Anywhere Accept payments from 190+ countries. Reach a global market with zero complexity. #### No Chargebacks or Fraud On-chain transactions are final. Eliminate risk of disputes and reversals forever. Example Transaction 1 % flat fee per transaction Customer Pays ₦100,000.00 Fee (1%) \-₦1,000.00 You Receive ₦99,000 Settled in minutes No setup fees No monthly costs All major Nigerian banks supported ## Multiple Blockchains Supported Bitcoin BNB Chain Solana Ethereum Tron Litecoin Polygon Avalanche Read the full breakdown [Crypto Payments in Nigeria: Why Your Business Should Accept Crypto](https://coincircuit.io/blog/accept-crypto-payments-nigeria/) ### Start Accepting Crypto in Nigeria Nigerian merchants are already processing payments with CoinCircuit. 1% flat fee, NGN settlement, no setup costs. [Get Started Free](https://dashboard.coincircuit.io/signup) [Contact Sales](https://coincircuit.io/contact/) --- # Crypto Payment Infrastructure for Africa | CoinCircuit > Accept crypto payments across Nigeria, South Africa, Ghana, Kenya, and 30+ countries. Low fees, fast settlement, and one unified API. Source: https://coincircuit.io/africa/ Markdown: https://coincircuit.io/africa.md Africa # Crypto Infrastructure for Africa The all-in-one platform to accept crypto, settle to local banks, and manage payouts across Africa. [Get Started Free](https://dashboard.coincircuit.io/signup) [Contact Sales](https://coincircuit.io/contact/) 0+ African countries Supported markets 0% Sub-Saharan crypto is stablecoins Chainalysis, 2024 Flat fee per transaction No hidden costs 0 Blockchain networks Multi-chain ## Built for How Africa Pays African businesses face high cross-border fees, slow settlement, and limited payment options for international customers. Crypto fixes all three. ### Fast Local Settlement Crypto converts and settles to local bank accounts in minutes. No correspondent banking delays. ### Accept from 190+ Countries A customer in Berlin pays the same way as one in Lagos. One integration covers the world. ### Stablecoin Settlement Settle in USDT or USDC to avoid local currency volatility. Convert to fiat when rates work for you. ### One API for the Continent Integrate once. Accept payments across Nigeria, South Africa, Ghana, Kenya, and 20+ more markets. ### Local Bank Payouts Settle to local banks in NGN, ZAR, GHS, KES, and more. Your money lands where your business operates. ### 1% Flat Fee No setup costs, no monthly charges, no minimum volume. Pay only when you get paid. ## Active Across the Continent Merchants in these countries accept crypto with CoinCircuit. [Nigeria](https://coincircuit.io/nigeria/) South Africa Ghana Kenya Expanding across the continent with 20+ more markets ## Multiple Blockchains Supported Bitcoin BNB Chain Solana Ethereum Tron Litecoin Polygon Avalanche ### Crypto Payment Infrastructure for Africa One API. 30+ countries. Low fees. Local settlement. Join African merchants processing payments with CoinCircuit. --- # Frequently Asked Questions | CoinCircuit > Get answers to common questions about CoinCircuit crypto payments, fees, supported currencies, integrations, and settlements. Source: https://coincircuit.io/faq/ Markdown: https://coincircuit.io/faq.md CoinCircuit FAQ Questions # Frequently Asked Questions Common questions about integration, supported chains, settlement, pricing, and security. ## How long does it take to integrate CoinCircuit? Integration About an hour. CoinCircuit provides a fully documented REST API with OpenAPI specs, SDKs for TypeScript, Python, Go, and PHP, and an MCP-compatible AI agent that can scaffold your entire integration. A basic checkout is a single POST request. ## Which blockchains and assets are supported? Networks CoinCircuit supports Ethereum, Polygon, BNB Smart Chain, Arbitrum, Optimism, Avalanche, TRON, and Solana. Accepted assets include USDT, USDC, DAI, ETH, BTC and native chain tokens. New chains and tokens are added based on merchant demand. ## How does settlement work? Settlement Once a payment is confirmed on-chain, it is automatically settled to your account. You can choose to settle in a stablecoin (e.g. USDC) or convert to your local fiat currency. Settlements are processed instantly. ## What security measures are in place? Security We follow industry-standard security practices: data is encrypted in transit and at rest, integrations are authenticated, keys and credentials are stored securely with strict access controls, and systems are continuously monitored. We also perform regular security reviews, testing, and third-party audits. ## What are the fees? Pricing CoinCircuit charges a simple flat fee per transaction — no monthly minimums, no setup fees, no integration fees, and no charges for failed or expired payment sessions. ## Do you support partial payments? Features Yes. If a customer sends less than the required amount, the session stays open until the full balance is received or the session expires. This is useful for large invoices or customers splitting payments across wallets. ## Can I accept crypto payments in Nigeria? Nigeria Yes. CoinCircuit is built for Nigerian businesses. Accept Bitcoin, USDT, USDC and 50+ cryptocurrencies with instant settlement in NGN to your local bank account. We support all major Nigerian banks. ## How do I receive naira from crypto payments? You decide how to settle. CoinCircuit can settle payments to your Nigerian bank account in naira, or keep your balance in stablecoins. Your customer pays in any supported asset, and you receive funds in the currency you choose. ## Which African countries does CoinCircuit support? Africa CoinCircuit supports businesses across Africa, with primary coverage in Nigeria, South Africa, Ghana, Kenya, and Tanzania. Merchants can accept crypto payments and settle in local fiat currencies. --- # Security | CoinCircuit > Enterprise-grade security: AES-256 encryption, TLS 1.3, OAuth 2.0, key management, access controls, and audited infrastructure. Source: https://coincircuit.io/security/ Markdown: https://coincircuit.io/security.md Security & Compliance # Enterprise Security Bank-grade encryption, continuous monitoring, and compliance built into every layer of our platform. [Contact Security Team](https://coincircuit.io/contact/) [View Documentation](https://coincircuit.io/docs/) ## Designed for Defense The protective layers and cryptographic standards securing the CoinCircuit platform. Encryption at rest ### Data Encryption All sensitive user data is encrypted using AES-256-GCM, providing secure and resilient data protection. *Data Encryption* Sensitive channels ### End-to-End Encryption For highly sensitive communications, we employ end-to-end encryption to ensure minimal exposure of private data. *End-to-End Encryption* API and webhooks ### API Security Our APIs use robust authorization and HMAC signatures to verify request integrity, preventing tampering during transmission. *API Security* ## Standards & Operations Meeting global security demands and maintaining continuous defense structures ### Non-Custodial Design We employ architectural patterns that ensure you maintain control of your funds where applicable. ### Cloud Infrastructure Built on highly-available, distributed cloud environments with industry-standard security practices. ### Continuous Monitoring Real-time threat detection and anomaly monitoring applied across our network operations. ### Access Controls Granular Role-Based Access Controls (RBAC) and multi-factor authentication requirements. ### Questions About Our Security? Our security team is here to answer your questions and provide detailed information about our practices. --- # About CoinCircuit | Crypto Payment Infrastructure for Africa > CoinCircuit simplifies crypto payments for African businesses and developers. Secure APIs, hosted checkout, and reliable global settlements. Source: https://coincircuit.io/about/ Markdown: https://coincircuit.io/about.md The CoinCircuit Mission # Building the future of digital commerce. Simplifying global payments with infrastructure purpose-built for African businesses and trusted by companies worldwide. 0+ Blockchains $0+ Daily Volume 0% Uptime SLA Merchants ## Our Origin Story CoinCircuit was created to solve a fundamental problem facing businesses across Africa: the inability to reliably accept global digital payments. Customers were ready to pay with crypto, but merchants lacked a fast, affordable, and trustworthy way to receive it. We built CoinCircuit to bridge Africa to the digital economy. Across the continent, traditional payment rails are slow, expensive, and often unreliable. Existing crypto payment tools were either too complex, unstable, or not designed for African markets. CoinCircuit was engineered to change that: a unified platform that lets any business accept Bitcoin, Ethereum, USDT, USDC, BNB, Solana, and more, instantly, securely, and without technical overhead. While our mission began with empowering African merchants, our infrastructure is global. Companies around the world can build with our infrastructure. Our network provides fast settlements, intelligent routing, and enterprise-grade reliability, enabling businesses everywhere to operate in a truly borderless economy. ## Engineered for Trust & Scale Our core operating principles. ### Multi-Chain Native Optimized multi-chain payments designed for emerging markets first, with global support for BTC, ETH, SOL, USDT, USDC, BNB, and more. ### Instant Settlements Fast, predictable payouts in both local African currencies and global currencies, enabling merchants to operate without borders. ### Data-Driven AI Actionable insights into your digital payment flows, built to help growing markets scale efficiently and globally. ### Ready to accept Crypto? Join hundreds of businesses using CoinCircuit to process payments instantly. Get started in minutes with our simple API. [View Documentation](https://coincircuit.io/docs/) [Contact Sales](https://coincircuit.io/contact/) --- # Ambassador Program | Scale with CoinCircuit > Join the CoinCircuit Ambassador Program. Get 0% processing fees and 200 free transactions covered. Source: https://coincircuit.io/ambassador/ Markdown: https://coincircuit.io/ambassador.md Global Ambassador Program # Shape the Future of Payments Join our exclusive network of innovators. Help businesses scale their crypto payments and unlock incredible perks while doing it. ## What is CoinCircuit? CoinCircuit is a crypto payment infrastructure built for both traditional businesses and autonomous AI agents. We abstract away blockchain complexity so merchants receive seamless crypto payments with zero chargebacks. #### 1\. Join the Core Submit your application and become an official CoinCircuit ambassador. #### 2\. Build & Educate Integrate the platform into your projects and help local merchants accept crypto. #### 3\. Unlock Perks Enjoy 0% processing fees and 200 free transactions covered on us. ## Ambassador Expectations As an Ambassador, you will be a key partner in expanding our network. You'll help businesses accept crypto, build exciting new projects with our tools, and actively share your journey to grow the community. #### Build Projects Use the CoinCircuit product in the real world. Actively integrate our APIs into projects and applications you build. #### Expand the Reach Identify businesses and builders in your network and introduce them to the possibilities of seamless crypto payments. #### Share Experiences Be vocal on social media. Share your building experiences, insights, and lessons learned using CoinCircuit to foster community growth. ## Unmatched Perks As an ambassador, you receive massive incentives to build using CoinCircuit's payment stack. ### 0% Processing Fees Experience frictionless money movement. As an ambassador, all your platform processing fees are entirely waived. ### 200 Free Transactions Completely covered by CoinCircuit. Try the system out, build your projects, and submit transactions entirely on us. ### Ready to Scale the Economy? Submit your application and let's bring crypto & AI payments to the world, together. [Apply](https://docs.google.com/forms/d/e/1FAIpQLSd788ZJ2KnuU8QKDo6Llx76XUlS6E-osHEQIgWTMVW17G8A2Q/viewform?usp=publish-editor) [Learn More](https://coincircuit.io/docs/) --- # Ambassador Terms | CoinCircuit > Terms of Service and guidelines for the CoinCircuit Core Ambassador Program. Source: https://coincircuit.io/ambassador/terms/ Markdown: https://coincircuit.io/ambassador/terms.md # Ambassador Program Terms Last Updated: March 26, 2026 ## 1\. Acceptance of Terms By applying to and participating in the CoinCircuit Core Ambassador Program (the "Program"), you agree to abide by these Terms of Service. These terms supplement the standard CoinCircuit Terms of Service and primarily govern the distribution and limitations of Ambassador perks and incentives. CoinCircuit reserves the right to modify or terminate this program at its sole discretion at any time. ## 2\. Program Incentives and Limitations ### 2.1. The 0% Processing Fee As part of the Ambassador Program, participating members are granted a **0% processing fee** perk to enable frictionless building and testing. **Volume Limit:** The 0% fee perk applies to an ambassador's initial $5,000 USD in processing volume. After this volume is exceeded, standard platform processing fees are applied to subsequent transactions. ### 2.2. The 200 Free Transactions Ambassadors are granted 200 free transactions fully covered by CoinCircuit. This perk is intended to subsidize initial project launches and network familiarization. Once the 200 transaction limit is exhausted, standard network operations and fees will resume. ## 3\. Proper Use of Incentives The incentives provided under the Ambassador Program are intended explicitly to support authentic project building, merchant onboarding, and network growth. We ask that all ambassadors use these perks in good faith. Activities designed solely to exploit the fee limits, such as artificially inflating volume or creating duplicate integrations to bypass thresholds, are not permitted and may result in removal from the program. ## 4\. Program Updates CoinCircuit may update the volume limits or fee structures of the Ambassador Program as the network scales. We are committed to communicating any major changes clearly. We reserve the right to review ambassador status to ensure the program remains mutually beneficial. If you have any questions regarding these incentives or limits, please contact the team at [contact@coincircuit.io](mailto:contact@coincircuit.io). --- # AML Policy | CoinCircuit > CoinCircuit Anti-Money Laundering Policy. Source: https://coincircuit.io/aml/ Markdown: https://coincircuit.io/aml.md # AML Policy CoinCircuit is committed to maintaining effective crime prevention and detection measures to assist law enforcement agencies in combating financial crime. We have adopted a strict set of policies and procedures to fulfil our legal obligations under international anti-money laundering and anti-terrorism legislation. ## Background Information Money laundering is a process by which money and property (assets) obtained as a result of criminal activity are disguised as coming from a legitimate source. In essence, money laundering is a process in which "dirty money" obtained through criminal activity turns into "clean money", the criminal origin of which is difficult to trace. There are three recognized stages in the process of money laundering: - **Placement:** Involves the placement of proceeds from crime in the financial system. - **Layering:** Involves the transformation of proceeds of crime into another form and the creation of complex layers of financial transactions to complicate the audit trail and hide the source and ownership of the proceeds. - **Integration:** Involves the return of laundered income to the economy to create an idea of legitimacy. Money laundering starts with the proceeds of crime from the predicate offence. Predicate offences include tax evasion, drug trafficking, bribery, fraud, forgery, murder, robbery, counterfeiting, securities manipulation, and copyright infringement, among others. Terrorist financing is when you knowingly collect or provide property, such as money, directly or indirectly to terrorists. The main purpose of terrorist activities is to intimidate the public or to force government action. Terrorists need financial support to carry out terrorist activities and achieve their goals. Many of the techniques used for money laundering are also used in terrorist financing, including but not limited to concealing the channelling of funds and the use of third parties. ## 1\. Main Objectives - Clients' identities are satisfactorily verified in accordance with our risk-based approach before CoinCircuit does business with them - CoinCircuit knows its clients and understands their reasons for doing business with us both at the client acceptance stage and throughout the business relationship - Our staff are trained and made aware of both their personal legal obligations and the legal obligations of CoinCircuit - Our staff is trained to be vigilant for activities where there are reasonable grounds for suspicion that money laundering could be taking place and to report to the Compliance Officer - Sufficient records are kept for the required period - We establish, maintain and implement appropriate procedures to achieve these objectives ## 2\. General Principles ### Anti-Money Laundering Policy CoinCircuit has implemented policies, procedures and controls designed to prevent criminals from using our platform to launder the proceeds of crime. These policies and procedures are tailored to the risk posed to individual customers. ### Customer Due Diligence ('CDD') CoinCircuit has established customer due diligence procedures to identify the users of its services and, in respect of higher risk customers, the primary beneficial owners and origin of funds. These procedures include knowledge of the nature of our customers' business and vigilance for anomalous transactions. In general, the CDD policy has been adopted by CoinCircuit to successfully fulfil the following objectives: - Identification and verification of the applicant for business - Identification and verification of the beneficial owner, where applicable - Identification and verification when the applicant for business does not act as principal - Obtaining information on the purpose and intended nature of the business relationship - Conducting ongoing monitoring of the business relationship - Establishing the source of wealth and source of funds - Setting up of a customer acceptance policy and ensuring that the applicant for business meets the requirements set out in such policy CoinCircuit is strictly prohibited from keeping anonymous accounts or accounts in fictitious names. ### Suspicious Transactions Unexplained or anomalous transactions or activities suspected to be related to criminal activity should be reported immediately in writing to the Compliance Officer, who will determine whether the suspicion should be reported to Law Enforcement. ### Training All personnel must be informed of their individual and collective responsibilities and CoinCircuit's anti-money laundering policies. Personnel are provided with training to enable them to understand the vulnerabilities of CoinCircuit's business and to recognize and report suspicious activities. ### Record-Keeping CoinCircuit keeps records of who has been trained and the time and form of the training sessions. We keep all records confirming the identity of our customers for at least 7 years after the end of the business relationship. We also keep records of any internal reports of suspicion made to the Compliance Officer. ## 3\. Our Responsibilities All cryptocurrency payment service providers are required by International Law to: - Develop a programme to ensure compliance with reporting, record keeping and customer identification requirements - Comply with customer identification rules and maintain specific records for specific transactions - Report suspicious transactions, large cash transactions and information related to terrorist property ## 4\. Risk-Based Approach Risk can be defined as the likelihood of an event and its consequences. In the context of money laundering/terrorist financing (ML/TF), risk means: - **At the national level:** ML/TF threats and vulnerabilities that jeopardise the integrity of the financial system - **At the Company level:** Threats and vulnerabilities that put CoinCircuit at risk of being used to facilitate ML/TF All clients default to low risk, UNLESS risk factors are present. Automatic high-risk characteristics include: - Politically exposed person - A client where a suspicious transaction or terrorist financing report has been filed - A client who is an identified terrorist - A client for whom we are unable to obtain beneficial ownership information - A client from high-risk country ### Client Characteristics, Product, Service, Delivery Channel: - Politically exposed person, head of international organization and close associates - Unknown source of funds - Large transaction orders from/to high-risk foreign jurisdictions - Third party involvement without reasonable justification - Occupation – High-risk occupations (e.g., cash intensive businesses, offshore business, business in high-risk countries, online gambling) - Client's business structure or transactions seem unusually complex - Non face-to-face client identification without justifiable reason ### Geography: - Client resides outside local or normal client area - Client resides in known crime area - Client has offshore business activities - Client connections to high-risk countries ### Other Suspicious Transaction Indicators: - Volume/timing/complexity of transactions inconsistent with the client's personal/business activity and/or purpose of the services/account - Value of deposits/transfers inconsistent with occupation or source of funds - Presence of any suspicious transaction indicators outlined in the Background Information section ## 5\. Indicators of Suspicious Transactions or Potential High-Risk Clients The following are examples of general and industry-specific indicators that may give you reasonable grounds to suspect that a transaction involves money laundering or terrorist financing. The presence of one or more of these factors does not automatically mean that the transaction should be reported, but it does indicate that a more in-depth examination is required. ### General Indicators: - Client admits to or makes statements about involvement in criminal activities - Client refuses or tries to avoid providing information required, or provides information that is misleading, vague, or difficult to verify - Client produces seemingly false documentation that appears to be counterfeited, altered or inaccurate - Client appears to have accounts with several financial institutions in one area for no apparent reason - Client repeatedly uses an address but frequently changes the name involved - Client shows uncommon curiosity about internal controls and systems - Client presents confusing details about the transaction - Client makes inquiries that would indicate a desire to avoid reporting - Client is involved in unusual activity for that individual or business - Client seems very familiar with money laundering or terrorist activity financing issues - Client refuses to produce personal identification documents - Client frequently travels to a high-risk country ### Industry-Specific Examples: - Client requests cryptocurrency exchanges at rates that exceed posted rates - Client wants to pay transaction fees that exceed posted fees - Client exchanges currency and requests the largest possible denomination in cryptocurrency - Client knows little about recipient wallet address and contact details, or is reluctant to disclose this information - Client enters into transactions with counterparties in locations that are unusual for the client - Client instructs that funds are to be picked up by a third party on behalf of the payee - Client makes large cryptocurrency purchases inconsistent with known business plans - Client makes purchases in large volumes without clear business justification ## 6\. Data Request To mitigate the risks associated with money laundering and terrorist financing, we strictly do not accept or send payments to third parties (unidentified). Each customer may only send and receive payments through their own accounts, including cryptocurrency wallets, bank accounts, and payment system accounts. In accordance with KYC ("Know Your Customer") policy, our employees are authorised to carry out customer verification. In this case, the customer is required to provide the following information: - Information about the services for which the funds were received - Documentation confirming the receipt and withdrawal of funds - Additional information that may be requested We reserve the right to refuse to process a transaction at any stage if it is suspected to involve money laundering or other criminal activity. ## 7\. Restricted Activities and Clients To mitigate and control ML risk related to clients, CoinCircuit does not provide services and refuses account opening for the following clients with unacceptable risk levels: ### Private Individuals with the Following Characteristics: - Information of negative nature is available about the client, indicating their possible relation to proceeds of crime, money laundering or terrorism - Client funds have previously been frozen or arrested in connection with suspected criminal activity - Client is trying to avoid provision of information or trying to hide their economic activity - Trafficking in arms and ammunition - Unlicensed foreign currency exchange intermediary services (such as forex dealers, binary options), as well as other unlicensed investment services - Escort services organization/activities and/or distribution of erotic/pornographic videos and pictures - Cash collection services - Debt recovery services - Drug distribution and controlled substances - Pyramid schemes and multi-level marketing - Telemarketing - Pawnshop services - Tobacco and alcohol products distribution ### Legal Persons with the Following Characteristics: - Information of negative nature is available indicating possible relation to proceeds of crime, money laundering or terrorism - Unlicensed reinsurance services with lack of proper supervision - Investment services when the service provider is not properly licensed - Legal entities which are recognized as shell companies - Unlicensed gambling services organization - The reason for the legal entity's establishment is unclear and information about economic objectives are vague and ambiguous - Unlicensed foreign currency exchange intermediary services - Client's transactions or payments are complex, unusually large or unclear in terms of their legal and economic objective In accordance with internal AML/CFT procedures, CoinCircuit has customers in two risk categories - low-risk and high-risk customers. For high-risk customers, Enhanced Due Diligence (EDD) should be carried out. ### A High-Risk Client is Someone: - Who is a politically exposed person, their family member or a close associate - With whom financial claims and either arising out of or related obligations exceed $10,000 USD ## 8\. Sanctions CoinCircuit is prohibited from transacting with individuals, companies and countries that are on prescribed Sanctions lists. CoinCircuit will therefore screen against the relevant sanctions lists in the jurisdictions in which we operate. CoinCircuit has no AML Risk Appetite for establishing or maintaining a customer or counterparty relationship with a natural person or legal entity designated on any of the below lists or where otherwise prohibited by applicable law or regulation: - Sanction lists administered by the United States Office of Foreign Assets Control (OFAC) - The United Nations Security Council Sanctions List (UN) - The Consolidated List of European Union Financial Sanctions (EU) - List of Specially Designated Nationals and Blocked Persons - Any other applicable sanctions lists In addition, CoinCircuit pays particular attention to entities from countries which are on the list of non-cooperative countries and territories drawn up by the Financial Action Task Force (FATF) and to monetary operations or transactions performed by or on behalf of them. ## 9\. List of Non-Serviced Countries CoinCircuit does not open accounts and does not provide services to clients from the following countries and jurisdictions: Afghanistan, Balkans, Belarus, Bosnia Central African Republic (CAR), Crimea, Cuba Democratic Republic of Congo (DRC), China Eritrea, Guinea-Bissau, Haiti Iran, Iraq, Ivory Coast, Lao Lebanon, Liberia, Libya, Mali Moldova, Myanmar (Burma), Nicaragua North Korea, Pakistan, Republic of Guinea Russia, Serbia/Yugoslavia, Somalia Sri Lanka, South Sudan, Sudan, Syria Trinidad & Tobago, Ukraine, United States Vanuatu, Venezuela, Yemen, Zimbabwe **Note:** CoinCircuit does not on-board US persons or entities. We adopt the list of high-risk countries as released by local and foreign regulatory authorities from time to time. ## 10\. Monitoring for Suspicious Activity CoinCircuit's AML policy includes customer and beneficial owner due diligence, ongoing AML monitoring and AML reporting policies. At various points in time, CoinCircuit may request information regarding the transactions carried out through the customer's account and the parties of the respective payment. If the customer does not respond sufficiently or within a timely manner, CoinCircuit reserves the right to reject any respective payments subject to the requirements of the applicable AML laws and regulations. ## Contact Information If you have any questions about our AML Policy or need to report suspicious activity, please contact our Compliance Officer: - **Company Name:** CoinCircuit Limited - **Contact:** contact@coincircuit.io Last Updated: November 10, 2025 --- # Blog & Articles | CoinCircuit > Latest insights on crypto payments, agentic AI commerce, African fintech, and Web3 technology from the CoinCircuit team. Source: https://coincircuit.io/blog/ Markdown: https://coincircuit.io/blog.md Updates & Insights # CoinCircuit Blog Discover the latest engineering insights, blockchain payment architectures, and updates directly from the team building CoinCircuit. [*Introducing Binance Pay on CoinCircuit* Product Updates / Less than 1 min read ## Introducing Binance Pay on CoinCircuit CoinCircuit merchants can now accept Binance Pay. Customers pay from their Binance account in one tap, and businesses settle in stablecoins or local currency. By Chidubem Ogbuefi Published Oct 16, 2026 ](https://coincircuit.io/blog/binance-pay/)[*Crypto Payments Across Africa: Five Markets, Five Payment Stacks* Global Architecture ## Crypto Payments Across Africa: Five Markets, Five Payment Stacks Sub-Saharan Africa processed $205 billion in on-chain value in 2024-2025. Each market has different blockchain preferences, regulatory frameworks, and settlement needs. Mar 26, 2026 ](https://coincircuit.io/blog/crypto-payments-africa/)[*Crypto Payments in Nigeria: Why Your Business Should Accept Crypto* ## Crypto Payments in Nigeria: Why Your Business Should Accept Crypto $96 billion in crypto transactions flowed through Nigeria according to the SEC. 88.2% of businesses that added crypto payments reported increased revenue. Here is why Nigerian businesses should accept crypto, what it costs not to, and how to start. ](https://coincircuit.io/blog/accept-crypto-payments-nigeria/)[*Stablecoins vs CBDCs: What the Data Says for African Fintech Builders* ## Stablecoins vs CBDCs: What the Data Says for African Fintech Builders eNaira has 13 million wallets and 270,000 active users. USDT on Tron moves billions monthly across Africa. The numbers tell the story. Mar 24, 2026 ](https://coincircuit.io/blog/stablecoins-vs-cbdcs/)[*The Multi-Chain Merchant: Why Your Customers Are on Different Blockchains and What to Do About It* ## The Multi-Chain Merchant: Why Your Customers Are on Different Blockchains and What to Do About It Which blockchains your customers actually use, what the data says, and why single-network checkout kills conversion. Mar 23, 2026 ](https://coincircuit.io/blog/multi-chain-merchant-conversion-rates/)[*How to Sign a Gasless Stablecoin Payment* Developer Guide ## How to Sign a Gasless Stablecoin Payment Code examples for signing gasless stablecoin payments with EIP-3009 (USDC on Base, Arbitrum), Permit2 (USDC, USDT on Base, Arbitrum, BSC), and Solana partial transaction signing. Mar 21, 2026 ](https://coincircuit.io/blog/how-to-sign-gasless-payment/)[*x402: How to Accept Payments from AI Agents on Your API* Machine Economy ## x402: How to Accept Payments from AI Agents on Your API A developer guide to x402 gasless payments: EIP-3009, Permit2, and Solana signing schemes, resource server integration, and settlement via the CoinCircuit API. Mar 18, 2026 ](https://coincircuit.io/blog/x402-machine-to-machine-payments/)[*The Agentic Web: Why AI Assistants Need Crypto Rails to Function* ## The Agentic Web: Why AI Assistants Need Crypto Rails to Function AI agents spend real money on APIs, compute, and data, but traditional payment rails block them at every step. Stablecoin infrastructure fills the gap. Mar 16, 2026 ](https://coincircuit.io/blog/ai-assistants-crypto-rails/) ## In The Press Read what others are saying about CoinCircuit [*For businesses tired of saying no to crypto payments, CoinCircuit has an answer* Press 5 min read ## For businesses tired of saying no to crypto payments, CoinCircuit has an answer CoinCircuit, which launched in December 2025, is a Nigerian startup building payment infrastructure that allows businesses and individuals to accept crypto payments without becoming crypto businesses themselves. MEXC News (TechCabal) Jan 16, 2026 ](https://www.mexc.co/en-NG/news/491159) ### Stay up to date Connect with other developers and keep track of new features. [Join Community](https://coincircuit.io/community/) [Read the Docs](https://coincircuit.io/docs/) --- # Brand Assets | CoinCircuit > Official CoinCircuit brand assets and a searchable crypto logo gallery for design systems, product UI, and marketing collateral. Source: https://coincircuit.io/brand/ Markdown: https://coincircuit.io/brand.md Brand Center # Brand Assets Official logos, brand marks, and a searchable crypto logo library for your integrations and design work. ## CoinCircuit Logos Official logo files for product, partner, and campaign usage. *CoinCircuit Horizontal Logo* ### CoinCircuit Horizontal Logo Primary lockup for websites, banners, and presentations. [PNG](https://coincircuit.io/assets/coincircuit/logo-full-horizontal.PNG) *CoinCircuit Vertical Logo* ### CoinCircuit Vertical Logo Great for profile placements and stacked layouts. [PNG](https://coincircuit.io/assets/coincircuit/logo-full-vertical.png) *CoinCircuit Monogram* ### CoinCircuit Monogram Compact mark for icons, avatars, and small cards. [PNG](https://coincircuit.io/assets/coincircuit/logo.png) ## Crypto Logo Library 484 logos available. Search to find what you need. / btcethusdtusdcbnbsolxrpadamaticavaxdotltc Popular [btc](https://coincircuit.io/assets/crypto/btc.svg) [eth](https://coincircuit.io/assets/crypto/eth.svg) [usdt](https://coincircuit.io/assets/crypto/usdt.svg) [usdc](https://coincircuit.io/assets/crypto/usdc.svg) [bnb](https://coincircuit.io/assets/crypto/bnb.svg) [sol](https://coincircuit.io/assets/crypto/sol.svg) [xrp](https://coincircuit.io/assets/crypto/xrp.svg) [ada](https://coincircuit.io/assets/crypto/ada.svg) [matic](https://coincircuit.io/assets/crypto/matic.svg) [avax](https://coincircuit.io/assets/crypto/avax.svg) [dot](https://coincircuit.io/assets/crypto/dot.svg) [ltc](https://coincircuit.io/assets/crypto/ltc.svg) --- # Careers at CoinCircuit | CoinCircuit > Explore open Brand Designer and Marketing & Growth roles at CoinCircuit. Read the role details and apply with your portfolio or previous work. Source: https://coincircuit.io/careers/ Markdown: https://coincircuit.io/careers.md Careers at CoinCircuit # Build the future of payments. Join the team making digital payments simpler for businesses. Find your next role at CoinCircuit. [View open roles](#open-roles) ## Open positions Select a role to see the details and apply. 2 open roles [ Design ### Brand Designer View role ](https://coincircuit.io/careers/brand-designer/)[ Marketing ### Marketing & Growth ](https://coincircuit.io/careers/marketing-growth/) --- # Brand Designer | Careers | CoinCircuit > Apply for the Brand Designer role at CoinCircuit. Bring exceptional visual storytelling, original ideas, and obsessive attention to detail. Source: https://coincircuit.io/careers/brand-designer/ Markdown: https://coincircuit.io/careers/brand-designer.md [All open roles](https://coincircuit.io/careers/) Design # Brand Designer Shape how CoinCircuit looks, feels, and tells its story. [Apply for this role](#apply) ## About the role Help bring the CoinCircuit brand to life. We are looking for a designer who can turn ideas into distinctive visual stories and bring care to every part of the work. ## What you will do - Create visual concepts and brand assets that tell the CoinCircuit story. - Translate ideas into clear, compelling design across campaigns and content. - Carry a consistent visual point of view from the first concept to the final detail. ## What we are looking for - Exceptional visual storytelling and the ability to make an idea feel clear and memorable. - A strong creative instinct, original thinking, and a portfolio with a distinct point of view. - Obsessive attention to typography, composition, and the details that make a design work. ## What to share Share your portfolio or a selection of brand and design work. In your note, tell us about one project, the idea behind it, and your contribution. ## Apply for this role Brand Designer Name Email Link to a portfolio, project, or collection of your work. Tell us about your work and why this role interests you. --- # Marketing & Growth | Careers | CoinCircuit > Apply for the Marketing & Growth role at CoinCircuit. Bring exceptional storytelling, creative campaigns, and obsessive attention to detail. Source: https://coincircuit.io/careers/marketing-growth/ Markdown: https://coincircuit.io/careers/marketing-growth.md [All open roles](https://coincircuit.io/careers/) Marketing # Marketing & Growth Bring CoinCircuit to new audiences through ideas that connect. [Apply for this role](#apply) ## About the role Help more people discover and connect with CoinCircuit. We are looking for someone who combines compelling storytelling with a creative approach to marketing and growth. ## What you will do - Develop stories, content, and campaign ideas that make CoinCircuit easy to understand. - Find creative ways to reach new audiences and build interest in CoinCircuit. - Refine messaging and campaigns with careful attention to the audience and every detail. ## What we are looking for - Exceptional storytelling and the ability to turn an idea into a message people remember. - A strong creative instinct, original campaign thinking, and work that shows how you connect with an audience. - Obsessive attention to the words, presentation, and execution that make marketing effective. ## What to share Share content, campaigns, or growth work you are proud of. In your note, explain your contribution, the thinking behind the work, and any results you can share. ## Apply for this role Marketing & Growth Name Email Link to a portfolio, project, or collection of your work. Tell us about your work and why this role interests you. --- # API Changelog | CoinCircuit > Track CoinCircuit API changes, breaking changes, and migration guides. See what's new and how to upgrade your integration. Source: https://coincircuit.io/changelog/ Markdown: https://coincircuit.io/changelog.md [*CoinCircuit Logo* # CoinCircuit Docs ](https://coincircuit.io/) Connect MCP Open Search Keyboard Shortcut: CTRL - Introduction - Sandbox Environment - MCP Integration - Official SDKs - Authentication - Webhooks - Error Handling - Rate Limiting - Pagination Invoices Close Group - Create invoiceHTTP Method: POST - List invoicesHTTP Method: GET - Retrieve invoice by referenceHTTP Method: GET - PaymentsOpen Group - x402Open Group - TransactionsOpen Group - DepositsOpen Group - PayoutsOpen Group - Payout RecipientsOpen Group - BalanceOpen Group - SwapOpen Group - SettlementsOpen Group - CustomersOpen Group - RefundsOpen Group - Payment PagesOpen Group - MiscellaneousOpen Group - ModelsOpen Group Generate MCP [Powered by Scalar](https://www.scalar.com) Open Menu Developer Tools Configure Share Deploy v1.0 OAS 3.0.0 # CoinCircuit API Download OpenAPI Document json yaml # Introduction Welcome to **CoinCircuit**, crypto payment infrastructure for online payments, in-store payments, payouts, and refunds through a single API. New here? Start with the [Quick Start](https://coincircuit.io/docs/quick-start/) for a guided walkthrough. **Need help?** Use the AI assistant in the bottom-right corner for guidance while navigating the documentation. # Sandbox Environment Use sandbox to test your integration safely before going live. - **Production Base URL:** `https://api.coincircuit.io` - **Sandbox Base URL:** `https://sandbox-api.coincircuit.io` Use sandbox API keys (test keys) against the sandbox base URL, and live keys against production. # MCP Integration CoinCircuit provides a **Model Context Protocol (MCP)** server for seamless integration with AI-powered IDEs like **Cursor**, **Windsurf**, **Claude Desktop**, and more. **MCP URL:** `https://mcp.coincircuit.io` Generate an MCP access key from your CoinCircuit dashboard under **Developer > MCP Access Keys**, then add it to your config: ``` { "mcpServers": { "coincircuit": { "url": "https://mcp.coincircuit.io", "headers": { "x-mcp-key": "YOUR_MCP_KEY" } } } } ``` The MCP server works without authentication for documentation browsing and API schema discovery. Authentication is only required to execute tools (create payments, list transactions, etc.). # Official SDKs Install the CoinCircuit SDK for your language. **Node.js / TypeScript** ``` npm install coincircuit ``` **Python** ``` pip install coincircuit ``` **Checkout SDK** ``` npm install @coincircuit/checkout ``` [npm](https://www.npmjs.com/package/coincircuit) | [PyPI](https://pypi.org/project/coincircuit/) | [Checkout SDK](https://www.npmjs.com/package/@coincircuit/checkout) # Authentication Authenticate requests by including your API key in the `x-api-key` header. ``` x-api-key: your_api_key_here ``` # Webhooks CoinCircuit sends webhook events as payments progress. See the [Webhooks tab](https://coincircuit.io/api-reference/?tab=webhooks) in this page for detailed integration guidance. # Error Handling The API uses standard HTTP status codes to indicate the success or failure of a request. HTTP Status Description 400 Invalid input or malformed request 401 Invalid or missing authentication 404 Resource not found 409 Resource conflict 503 Service unavailable **Basic Error Example:** ``` { "success": false, "timestamp": "2026-01-23T23:33:55.685Z", "path": "/api/v1/payments", "method": "POST", "error": "Unauthorized", "message": "Unauthorized" } ``` # Rate Limiting The API is rate-limited to **20 requests per second**. Exceeding this limit will result in a `429 Too Many Requests` response. # Pagination List endpoints support pagination using `page` (default 1) and `size` (default 10, max 100) query parameters. **Response Metadata Example:** ``` "meta": { "page": 1, "size": 10, "total": 42, "totalPages": 5 } ``` Server: https://api.coincircuit.io Production Server ## Authentication Select No authentication selected Client Libraries Shell Ruby Node.js PHP Python More Select from all clients Node.js Axios ## Invoices ​ Copy link Create and manage invoices - post/api/v1/invoices - get/api/v1/invoices - get/api/v1/invoices/reference/{reference} Overview Ctrl K Webhooks # Overview How CoinCircuit delivers webhook events, with headers, retries, and idempotency. CoinCircuit sends webhook events to your endpoint as payments, payouts, refunds, deposits, and other resources change state. Each event is a POST request with a JSON body. ## Standard headers Every delivery carries these headers. Header X-CoinCircuit-Event The event type, e.g. `transaction.confirmed` X-CoinCircuit-Delivery-Id Unique id for this delivery X-CoinCircuit-Signature HMAC-SHA256 signature of the payload X-CoinCircuit-Timestamp Unix timestamp of the delivery ## Event identification Every event includes a unique `X-CoinCircuit-Delivery-Id`. Store the ids you have processed and skip repeats so the same event is never handled twice. ## Automatic retries Failed deliveries (any non-200 response) are retried with exponential backoff, roughly at 0m, 1m, 10m, then 1h. Return a 200 quickly to acknowledge receipt. ## Responding Acknowledge with a 2xx status as soon as you have stored the event, then do any heavy work asynchronously so the delivery does not time out. Introduction Getting Started **CoinCircuit** is crypto payment infrastructure. Accept payments online, in person, and from AI agents. Bill with invoices, send payouts, and issue refunds. ## What you can build - **Online payments.** Create a payment and redirect to a hosted checkout, or build your own UI on the API. - **In-store payments.** Share a payment page link or QR code, or take payments on a POS terminal at the counter. - **Invoices.** Send itemized invoices your customers pay in crypto. - **Agentic payments (x402).** Let AI agents and automated clients pay for your API per request, settled in stablecoins with gas covered. - **Payouts.** Withdraw your balance to a bank account or a crypto wallet. - **Refunds.** Refund a payment or an invoice, in full or in part. - **Deposit accounts.** Give each customer a reusable address to receive funds into their balance. - **Webhooks.** Get a signed event the moment a payment, payout, or refund changes state. ## Base URLs - **Production:** `https://api.coincircuit.io` - **Sandbox:** `https://sandbox-api.coincircuit.io` ## Start here Follow the Quick Start to take your first payment in a few minutes. To test without real funds first, set up the Sandbox. Releases - v2.6.0September 2026 - v2.5.0August 2026 - v2.4.0July 2026 - v2.3.0June 2026 - v2.2.0May 2026 - v2.1.0March 2026 - v2.0.0February 2026 # Changelog API changes, new features, migration guides, and deprecation notices, newest first. ## v2.6.0 September 2026 ### Payment Review Payments that need a compliance check are held rather than failed. You are told when a payment is held and again when it is decided. #### Payments Held for Review New Updated A held payment is neither completed nor failed. It waits, the session stays open, and you receive the final outcome as a normal payment webhook. ##### payment.under\_review webhook Some confirmed payments are held for a compliance check before they are credited. When that happens you receive payment.under\_review. The session stays open and does not expire while the check runs. It is followed by payment.completed, payment.partial or payment.failed once the check is decided, so treat under\_review as a waiting state, not an outcome. example.json ``` { "event": "payment.under_review", "data": { "session": { "state": "open", "payment": { "status": "under_review" } } } } ``` ##### New payment status: under\_review payment.status on a session can now be under\_review. A session in this state is still open and settles or fails later. Nothing changes for sessions that are not held. ## v2.5.0 August 2026 ### Settlement Currency Control Choose the currency a payment or a deposit account is settled into, independently of what you priced in and what your customer pays. Payment session responses return the settlement breakdown from creation. #### Settlement Currency Name the currency you want funds settled into on a payment or a deposit account, instead of taking the account currency from your settings. ##### Set the settlement currency on a payment POST /payments accepts a settlementCurrency. The customer still pays in the currency you priced in, and the payment is settled into the currency you named. Leave it out and the payment is settled into the account currency from your settings. ``` POST /payments { "amount": "10000.00", "currency": "NGN", "settlementCurrency": "USDT", "customer": { "email": "customer@example.com" } } ``` ##### Set the settlement currency on a deposit account POST /deposits/accounts accepts a settlementCurrency, applied to every deposit into that account. Leave it out and deposits settle on the default behavior. Your parent account is always default. ``` POST /deposits/accounts { "customerId": "123e4567-e89b-12d3-a456-426614174000", "settlementCurrency": "USDC" } ``` ##### settlements is always returned The settlements object is returned from the moment a payment session is created, so the settlement currency, conversion rate and fee split are available before the payment settles. net stays null until settlement completes, and is the field to check for whether a payment has settled. ``` // Session created, not yet paid { "settlements": { "currency": "USDT", "customerPaid": { "amount": null }, "gross": { "amount": "100.00", "conversionRate": "1.0" }, "fees": null, "net": null } } ``` ## v2.4.0 July 2026 ### Cross-Border Payouts, Per-Request Webhooks & Unified Recipients Send payouts to Kenya and Ghana from your stablecoin balance with locked quotes, route webhooks per request by passing a webhookUrl, and manage every payout recipient through one unified endpoint. #### Cross-Border Payouts Pay recipients in their local currency, funded from your USDT or USDC balance. Quote the price, lock it, then send. Kenya (KES) and Ghana (GHS) are live. ##### POST /payouts/cross-border/quote Price a cross-border payout before you send it. The response is the funding cost in your stablecoin balance, the FX conversion, the flat fee, and the total, with a quote id you lock the price with. Quotes expire after two minutes. ``` POST /payouts/cross-border/quote { "currency": "KES", "sourceCurrency": "USDT", "amount": "10000.00" } // Response { "id": "cbq_123e4567-e89b-12d3-a456-426614174000", "conversion": { "fromCurrency": "USDT", "toCurrency": "KES", "sourceAmount": "77.60", "targetAmount": "10000.00", "rate": "128.87" }, "fee": "1.50", "total": "79.10", "expiresAt": "2026-07-22T12:02:00.000Z" } ``` ##### Pay recipients in their local currency POST /payouts now settles to Kenya (KES) and Ghana (GHS), funded from your USDT or USDC balance. Set currency to the local currency the recipient receives, sourceCurrency to the stablecoin you fund from, and pass the quote id to pay exactly the price you were quoted. ``` POST /payouts { "currency": "KES", "sourceCurrency": "USDT", "amount": "10000.00", "recipientId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "quoteId": "cbq_123e4567-e89b-12d3-a456-426614174000" } ``` ##### Mobile money recipients Save mobile money recipients for cross-border payouts through the unified recipients endpoint. The kes\_mobile\_money and ghs\_mobile\_money types take the provider and account details for the corridor. ``` POST /recipients { "type": "kes_mobile_money", "label": "Field agent", "details": { "phoneNumber": "254712345678", "accountName": "Jane Wanjiku", "institutionCode": "MPESA" } } ``` #### Per-Request Webhook URLs Override your dashboard webhook URL for a single object by passing a webhookUrl when you create it. ##### Set a webhook URL per request Pass a webhookUrl when you create a payout, refund, or invoice, or when you execute a swap. Webhooks for that object are delivered to the URL you pass instead of your dashboard webhook URL, so you can route events per environment, per integration, or per customer. Omit it to keep using your dashboard URL. ``` POST /payouts { "currency": "NGN", "amount": "10000.00", "recipientId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "webhookUrl": "https://your-api.com/webhooks/payouts" } // Payout webhooks for this payout are delivered to webhookUrl ``` ##### Honored across payout, refund, swap, invoice and payment events A per-request webhook URL applies to payout, refund, swap, and invoice events, and payment events. Your dashboard webhook toggle still governs whether anything is sent. example.text ``` // A per-request webhookUrl overrides your dashboard URL for: payout.* // set it when you create the payout refund.* // set it when you create the refund swap.* // set it when you execute the swap invoice.* // set it when you create the invoice payment.* // set on the checkout session (invoices cover their payment too) ``` #### Unified Payout Recipients Deprecated Every payout recipient (crypto address, bank account, or mobile money) is created and managed through one /recipients endpoint. The separate bank account and crypto address endpoints are deprecated. ##### Individual recipient endpoints deprecated The separate endpoints for bank accounts and crypto addresses are deprecated. Create and manage every payout recipient through the unified /recipients endpoint. The individual endpoints keep working for existing integrations but are no longer documented. Before ``` // Deprecated: one endpoint per recipient type POST /bank-accounts { accountName, accountNumber, bankCode } POST /crypto-addresses { chain, address, label } ``` After ``` // Unified: one endpoint, the type field selects the shape POST /recipients ``` ##### One endpoint for every recipient type POST /recipients creates a recipient of any type. The type field selects the shape of details: a crypto address, an NGN bank account, or a mobile money account for cross-border payouts. List, fetch, and delete all recipients through the same resource. ``` // Crypto address POST /recipients { "type": "crypto_address", "label": "Ops wallet", "details": { "chain": "tron", "address": "TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC" } } // NGN bank account POST /recipients { "type": "ngn_bank_account", "label": "Payroll", "details": { "accountNumber": "0123456789", "bankCode": "058" } } ``` ## v2.3.0 June 2026 ### Deposit Accounts, Balance Ledger & Webhooks Deposit accounts you can issue per customer, a balance API that returns all your currencies in one call, a balance transactions ledger to inspect every entry that moved your balance, and new deposit and swap webhooks. #### Deposit Accounts Issue a deposit account per customer (or a parent account for your own balance) and provision its pay-in identities: static crypto deposit addresses and NGN virtual accounts. A deposit settles into the account it was issued for. ##### Issue a deposit account per customer Create a deposit account for each of your customers, or a single parent account for your own balance. A deposit account is the container that owns its pay-in identities (static crypto addresses and NGN virtual accounts) and is what a deposit settles into. Pass an existing customerId; omit it to create your parent account. ``` POST /deposits/accounts { "customerId": "123e4567-e89b-12d3-a456-426614174000" } // Omit "customerId" to create the parent (own-balance) account ``` ##### Issue a pay-in identity into an account Add a pay-in identity to a deposit account: a static crypto deposit address or an NGN virtual account. Funds sent to any identity credit the account holder. One endpoint serves both; the type field selects which identity to issue. ``` // static crypto deposit address POST /deposits/accounts/:id/identities { "type": "static_deposit_address", "chain": "ethereum" } // NGN virtual account POST /deposits/accounts/:id/identities { "type": "ngn_virtual_account", "bvn": "12345678901" } ``` ##### Retrieve and list deposit accounts Fetch a single account with its identities, the parent account, or a customer's account, and list all accounts filtered by status. ``` GET /deposits/accounts/:id GET /deposits/accounts/parent GET /deposits/accounts/by-customer/:customerId GET /deposits/accounts?status=active&page=1&size=20 ``` #### Balance Transactions A ledger feed of every entry that moved your balance, with rich source linkage and per-entry before/after balances. ##### GET /balance/transactions A paginated ledger of every entry that moved your balance: deposits, payments, payouts, swaps, refunds, and fees. Filter by source, status, direction, currency, txHash, and date range. ``` GET /balance/transactions?source=payment_session¤cy=USDT { "success": true, "message": "Balance transactions retrieved successfully", "data": [ { "id": "bt_123456789_abcdef", "source": "payment_session", "sourceId": "123e4567-e89b-12d3-a456-426614174000", "sourceReference": "CC-1G3fDjgD93md", "direction": "credit", "status": "completed", "amount": "100.00", "currency": "USDT", "fee": "0", "reference": "...", "balanceBefore": { "available": "1000.00", "pending": "0.00", "total": "1000.00" }, "balanceAfter": { "available": "1100.00", "pending": "0.00", "total": "1100.00" }, "createdAt": "2026-06-01T10:30:00.000Z" } ], "meta": { "page": 1, "size": 10, "total": 42, "totalPages": 5 } } ``` ##### How to locate the source of an entry source tells you what created the entry. sourceReference is the reference you pass to that object's API (set for sessions, invoices, and payouts). sourceId is the id of the source object (set for sessions, invoices, payouts, swaps, and deposits). A deposit entry's sourceId is the deposit id, which you can fetch at GET /deposits/:id. ``` // session / invoice / payout entry { "source": "invoice", "sourceId": "...", "sourceReference": "CC-INV-001" } // swap entry (no reference) { "source": "swap", "sourceId": "...", "sourceReference": null } // deposit entry (sourceId resolves at GET /deposits/:id) { "source": "deposit", "sourceId": "dep_123456789_abcdef", "sourceReference": null } ``` #### Deposit & Swap Webhooks deposit webhooks notify you when a deposit is recorded, credited, or fails, and swap.completed / swap.failed webhooks notify you when a swap finishes. ##### deposit.processing, deposit.completed and deposit.failed Get notified about deposits to your balance. deposit.processing fires when a deposit is detected and is processing. deposit.completed fires when a deposit is completed and credited to your balance. deposit.failed fires when a deposit fails a compliance check and is rejected. The payload is a deposit object with the on-chain detail under crypto, or the bank transfer detail under fiat. ``` { "event": "deposit.completed", "data": { "id": "dep_123456789_abcdef", "type": "crypto", "status": "completed", "amount": "100.00", "currency": "USDT", "fee": "0.50", "netAmount": "99.50", "depositAccountId": "da_123456789_abcdef", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "firstName": "John", "lastName": "Doe", "email": "customer@example.com" }, "crypto": { "txHash": "0x...", "chain": "ethereum", "asset": "USDT", "fromAddress": "0xsender...", "toAddress": "0xmerchant...", "staticDepositAddress": { "chain": "ethereum", "address": "0xmerchant...", "createdAt": "2026-01-10T08:00:00.000Z" } }, "fiat": { "reference": "NMB-12345", "method": "bank_transfer", "payer": { "accountName": "John Doe", "accountNumber": "0123456789", "bankName": "Wema Bank", "bankCode": "035" }, "payee": { "accountName": "COINCIRCUIT/John Doe", "accountNumber": "9876543210", "bankName": "Nomba Bank", "bankCode": "090645" }, "ngnVirtualAccount": { "currency": "NGN", "accountNumber": "9876543210", "accountName": "COINCIRCUIT/John Doe", "bankName": "Nomba Bank", "bankCode": "090645", "accountReference": "CCVBA-7f3a9c12", "createdAt": "2026-01-10T08:00:00.000Z" } }, "createdAt": "2026-06-01T10:30:00.000Z", "completedAt": "2026-06-01T10:35:00.000Z" } } ``` ##### swap.completed and swap.failed webhooks Get notified when a balance swap finishes. swap.completed fires on a successful conversion; swap.failed includes a failureReason. Useful when you kick off swaps and want to react without polling. ``` { "event": "swap.completed", "data": { "swap": { "id": "f2908051-6326-4708-bc73-1153209e7689", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "4.00", "targetAmount": "5493.95", "rate": "1373.48767500", "status": "completed", "completedAt": "2026-05-29T20:25:23.680Z", "createdAt": "2026-05-29T20:25:23.640Z", "quotation": { "id": "99f41fc8-47e2-4f34-a1dd-64f52ee4ff0c", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "4.00", "targetAmount": "5493.95", "rate": "1373.487675", "executed": true, "expiresAt": "2026-05-29T20:25:38.553Z", "createdAt": "2026-05-29T20:25:23.556Z" } } } } ``` #### Deposits Deposits are listed and fetched at /deposits. ##### List and fetch deposits at /deposits Inbound deposits (crypto and bank transfer) are listed and fetched under a single resource. Each deposit carries a depositAccountId linking it to the deposit account it settled into. ``` GET /deposits GET /deposits/:id ``` ## v2.2.0 May 2026 ### Swap for On/Off Ramping New swap endpoints to convert between USDT and NGN directly from your balance. Supports instant on-ramping (NGN to USDT) and off-ramping (USDT to NGN) with rate locking and atomic execution. #### Swap Endpoints A quotation-based swap flow: estimate the conversion, lock the rate for 15 seconds, then execute atomically. Supports USDT/NGN in both directions with per-swap limits of 30,000 USDT or 50,000,000 NGN. ##### POST /swap/quotation Lock a swap rate for 15 seconds. Returns a quotation with the guaranteed rate, source and target amounts. Execute within the TTL to swap at the quoted price. ``` POST /swap/quotation { "fromCurrency": "USDT", "toCurrency": "NGN", "amount": "500.00" } // Response { "id": "quotation-uuid", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "500.00", "targetAmount": "747500.00", "rate": "1495.00000000", "executed": false, "expiresAt": "2026-05-12T10:00:15.000Z", "createdAt": "2026-05-12T10:00:00.000Z" } ``` ##### POST /swap/execute/:quotationId Execute a previously created quotation. Debits the source currency and credits the target currency atomically at the locked rate. Returns the completed swap details. ``` POST /swap/execute/quotation-uuid // Response { "id": "swap-uuid", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "500.00", "targetAmount": "747500.00", "rate": "1495.00000000", "status": "completed", "quotation": { "id": "quotation-uuid", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "500.00", "targetAmount": "747500.00", "rate": "1495.00000000", "executed": true, "expiresAt": "2026-05-12T10:00:15.000Z", "createdAt": "2026-05-12T10:00:00.000Z" }, "createdAt": "2026-05-12T10:00:00.000Z", "completedAt": "2026-05-12T10:00:05.000Z" } ``` ##### GET /swap/estimate Preview swap output without locking a rate. Use this to show users an estimated conversion before they commit. The rate is indicative and may change. ``` GET /swap/estimate?fromCurrency=USDT&toCurrency=NGN&amount=500.00 // Response { "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "500.00", "targetAmount": "747500.00", "rate": "1495.00000000" } ``` ##### GET /swap/quotation/:quotationId Retrieve a quotation by ID. Includes an executed flag indicating whether the quotation has been used. Use expiresAt to determine if the quotation is still valid. ``` GET /swap/quotation/quotation-uuid // Response { "id": "quotation-uuid", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "500.00", "targetAmount": "747500.00", "rate": "1495.00000000", "executed": true, "expiresAt": "2026-05-12T10:00:15.000Z", "createdAt": "2026-05-12T10:00:00.000Z" } ``` ## v2.1.0 March 2026 ### x402 Agent Payments, Base and Arbitrum New endpoints for AI agent payments via the x402 protocol, plus Base and Arbitrum added as supported blockchains for all payment sessions. #### Agent Payment Endpoints Endpoints for the x402 protocol: build payment requirements, verify a signed payment, and settle it. AI agents pay for API resources with gasless stablecoin transfers, and CoinCircuit handles verification, on-chain submission, and gas. ##### POST /x402/requirements Build the payment requirements for a resource from a chain, asset, and amount. The response is the ready-to-return 402 body, including the canonical accepts array a standard x402 client reads. ``` POST /api/v1/x402/requirements { "chain": "base", "asset": "USDC", "amount": "0.10", "resource": "https://your-api.com/api/premium-data" } // Response (return this with a 402 status) { "x402Version": 1, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "maxAmountRequired": "100000", "resource": "https://your-api.com/api/premium-data", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } ] } ``` ##### POST /x402/settle Settle a signed x402 payment. Send the agent's paymentPayload with the requirements you issued. CoinCircuit verifies the signature, covers gas, submits the transfer on-chain, and returns the transaction hash. Each signed payment settles once; a replay returns 409 Conflict. ``` POST /api/v1/x402/settle { "x402Version": 1, "paymentPayload": { "x402Version": 1, "scheme": "exact", "network": "eip155:8453", "payload": { "signature": "0xb91c5d2e8a4f0c7d3e6b9a1f2c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d", "authorization": { "from": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b", "to": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "value": "100000", "validAfter": "0", "validBefore": "1774055094", "nonce": "0x9b2c4d6e8f0a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e0f2a4b6c8d0e1f3a5b7c" } } }, "paymentRequirements": { "scheme": "exact", "network": "eip155:8453", "maxAmountRequired": "100000", "resource": "https://your-api.com/api/premium-data", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "maxTimeoutSeconds": 60, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } } // Response { "success": true, "data": { "id": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7", "txHash": "0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3", "status": "confirmed", "amlCheck": "passed", "network": "eip155:8453", "chain": "base", "asset": "USDC", "payer": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "amount": "0.10", "fee": "0", "blockNumber": 21048765, "explorerUrl": "https://basescan.org/tx/0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3", "createdAt": "2026-06-25T21:09:02.000Z" } } ``` ##### POST /x402/verify Dry-run a signed payment without touching the blockchain. Takes the same body as settle and runs the requirement and on-chain checks: destination, amount, timestamp, nonce replay, and sender balance. Returns isValid, with an invalidReason when a check fails. ``` POST /api/v1/x402/verify // Same body as settle: x402Version, paymentPayload, paymentRequirements // Response { "success": true, "data": { "isValid": true, "invalidReason": null, "payer": "0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b", "chain": "base", "asset": "USDC", "payTo": "0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b", "amount": "0.10" } } ``` ##### End-to-end x402 flow CoinCircuit is the x402 facilitator. Your server states what a request costs, the agent signs a gasless payment, and CoinCircuit verifies it, covers gas, settles on-chain, and returns the transaction hash. The flow is stateless. ``` Agent -> GET your protected resource Server -> POST /api/v1/x402/requirements (build the terms) Server -> Agent: 402 Payment Required (the accepts array) Agent -> signs a gasless payment, retries with the payload Server -> POST /api/v1/x402/settle (paymentPayload + requirements) CoinCircuit -> verifies, covers gas, settles on-chain, returns txHash Server -> delivers the resource ``` #### New Supported Blockchains Base (Coinbase L2) and Arbitrum are now fully supported for all payment sessions, settlements, and agent payments. ##### Base blockchain support Coinbase's Layer 2 blockchain is now available for all payment sessions. USDC on Base settles in under 2 seconds. Base is the default blockchain for EIP-3009 gasless agent payments. ##### Arbitrum blockchain support Arbitrum One is now available for all payment sessions. Supports USDC and USDT via both EIP-3009 and Permit2 signing schemes with sub-second finality. ## v2.0.0 February 2026 ### Payment API Transition and Payouts Unified Major updates to the Payment API and Payouts system, introducing new payload shapes, unified endpoints, and better error handling. #### Payment API Transition Updated session response shape, renamed webhook event types (session.\* → payment.\*), and a restructured amount object with inline settlements. Existing API keys are unaffected. New API keys automatically use the updated format. ##### Webhook event types renamed: session.\* → payment.\* Payment session webhook event types have been renamed. Previous keys used session.\* prefixes; new keys use payment.\* prefixes. The webhook payload shape (data.session.\*) is unchanged — only the event type string differs. This applies to all payment session outcome events. ``` // Previous event types "session.completed" "session.expired" "session.partial" "session.failed" ``` ``` // New event types "payment.completed" "payment.expired" "payment.partial" "payment.underpaid" "payment.failed" ``` ##### New API keys use the updated format automatically Versioning is tied to your API key. New API keys created in the dashboard automatically use the updated response format and new webhook event types. Existing API keys continue to receive the current responses and event types — no action required to preserve your current integration. example.javascript ``` // Existing key → receives current events and response shape // New key → receives updated events and response shape // No config needed — version is determined by which key you use ``` ##### Redesigned session response shape The session API response has been restructured. The top-level status field is replaced by state (open/closed). Amount and currency are flat strings instead of a nested object. The financial breakdown (gross, fees, net) moves to a separate settlements object. ``` // New session response { "id": "550e8400-e29b-41d4-a716-446655440000", "reference": "cs_ref_abc123xyz789", "state": "closed", "type": "payment", "amount": "10000.00", "currency": "NGN", "payment": { "status": "completed", "asset": "USDT", "chain": "tron", "amount": "6.84", "amountReceived": "6.84", "address": "T...", "txHash": "0x..." }, "settlements": { "currency": "NGN", "gross": { "amount": "10000.00", "conversionRate": "1.0" }, "fees": { "processing": { "amount": "100.00", "paidBy": "merchant" }, "gas": { "amount": "50.00", "paidBy": "merchant" } }, "net": { "amount": "9850.00" } }, "customer": { ... }, "createdAt": "...", "expiresAt": "...", "completedAt": "..." } ``` ##### state replaces status The top-level status field is now state — "open" while active and awaiting payment, "closed" once finalized. The payment outcome is available in payment.status. ``` // Previous { "status": "completed" } // "pending" | "completed" | "expired" | "failed" // New { "state": "closed" } // "open" | "closed" // payment outcome lives in payment.status ``` ##### settlements included in payment API response Payment session responses now include a settlements object inline with the settlement currency, gross amount with conversion rate, fee breakdown (processing + gas), and net amount. No need to call the settlements endpoint separately. ``` { "settlements": { "currency": "NGN", "gross": { "amount": "10000.00", "conversionRate": "1.0" }, "fees": { "processing": { "amount": "100.00", "paidBy": "merchant" }, "gas": { "amount": "50.00", "paidBy": "merchant" } }, "net": { "amount": "9850.00" } } } ``` #### Payouts API Deprecation & Migration The legacy payout endpoints (/payout/fiat, /payout/crypto) are deprecated and will be removed on March 30, 2026. The new /payouts endpoint unifies fiat and crypto payouts into a single request. ##### Payout API deprecated — migrate to /payouts by March 30 The existing /payout/fiat and /payout/crypto endpoints are deprecated and will be removed on March 30, 2026. Migrate to the new unified POST /payouts endpoint. Separate fee endpoints (/payout/fiat/fee and /payout/crypto/fee) are replaced by GET /payouts/fees. ``` POST /payout/fiat // fiat payouts POST /payout/crypto // crypto payouts GET /payout/fiat/fee // fiat fee lookup GET /payout/crypto/fee // crypto fee lookup ``` ``` POST /payouts // unified — specify method in body GET /payouts/fees // unified fee lookup ``` ##### Unified payout endpoint A single POST /payouts endpoint handles both fiat and crypto payouts. Specify the method in the request body. The bankAccountId and addressId fields are replaced by a single recipientId field. ``` // New unified request body { "method": "fiat", // "fiat" | "crypto" "currency": "NGN", "amount": "10000.00", // amount recipient receives "recipientId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "narration": "Payout", "reference": "CLIENT-REF-123" // optional idempotency key } ``` ##### Amount is what the recipient receives In the old API, amount was the total debited from your balance (including fees) — the recipient got less. In the new API, amount is exactly what the recipient receives. Fees are charged separately on top. No need to add fees to your amount. ``` // Old: amount = total deducted (fee included) { "amount": "10050.00" } // fee: 50.00 // recipient gets: 10000.00 ``` ``` // New: amount = what recipient gets (fee is separate) { "amount": "10000.00" } // fee: 50.00 // total deducted: 10050.00 ``` ##### Redesigned payout response The response replaces the nested amount object and separate bankAccount/crypto objects with flat amount/fee/total strings, a unified recipient object, and a conversion object when the payout asset differs from the balance currency. ``` // New payout response (USDT balance → USDC payout) { "id": "550e8400-e29b-41d4-a716-446655440000", "method": "crypto", "type": "manual", "status": "success", "amount": "100.00", "fee": "1.50", "total": "101.50", "currency": "USDC", "conversion": { "from": "USDT", "to": "USDC", "rate": "0.9998", "convertedAmount": "100.00" }, "recipient": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "type": "crypto_address", "details": { "chain": "tron", "address": "TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC" } }, "txHash": "0x...", "reference": "CLIENT-REF-123", "narration": "Payout", "createdAt": "...", "completedAt": "..." } ``` ### Migration Guide Follow these steps to transition to the new format. Each step is independent — you can adopt them incrementally. 1 #### Generate a new API key New API keys automatically use the updated format. Go to the dashboard → API Keys → create a new key. Your existing key keeps working as-is — use the new key in a test environment first before switching production traffic. 2 #### Update webhook event type handlers Replace all session.\* event type strings with the corresponding payment.\* equivalents in your webhook handler. example.js ``` // Replace each event type: "session.completed" → "payment.completed" "session.expired" → "payment.expired" "session.partial" → "payment.partial" "session.failed" → "payment.failed" ``` 3 #### Update payment.partial handler payment.partial (previously session.partial) is now strictly mid-flow. It only fires when partial payments are enabled and the session is still open awaiting more funds. Terminal underpayment always uses payment.underpaid. ``` // payment.partial → session still open, more payments expected if (event === "payment.partial") { // data.session.state === "open" notifyCustomerOfPartialPayment(data.session.payment.amountReceived); } // payment.underpaid → session closed, insufficient total received if (event === "payment.underpaid") { // data.session.state === "closed" initiateRefundFlow(data.session.payment.amountReceived); } ``` 4 #### Update session response parsing The session object has been restructured. Update any code that reads the nested amount object — amount and currency are now flat strings, status is replaced by state, and the financial breakdown moves to settlements. ``` // Previous — nested amount object session.status // "pending" | "completed" | "expired" | "failed" session.amount.requested.amount // "10000.00" session.amount.requested.currency // "NGN" session.amount.gross // { amount, conversionRate } session.amount.fees // { processing, gas } session.amount.net // { amount } // New — flat amount + settlements object session.state // "open" | "closed" session.amount // "10000.00" (plain string) session.currency // "NGN" (plain string) session.settlements.gross // { amount, conversionRate } session.settlements.fees // { processing, gas } session.settlements.net // { amount } ``` 5 #### Migrate payout endpoints Replace POST /payout/fiat and POST /payout/crypto with the unified POST /payouts. Add a method field to the request body and use recipientId instead of bankAccountId or addressId. Replace /payout/fiat/fee and /payout/crypto/fee with GET /payouts/fees. ``` // Old — separate endpoints POST /payout/fiat { balanceCurrency, amount, bankAccountId, narration } POST /payout/crypto { balanceCurrency, amount, addressId } // New — unified endpoint POST /payouts { method: "fiat" | "crypto", currency: "NGN", // was balanceCurrency amount: "10000.00", recipientId: "...", // was bankAccountId or addressId narration: "...", reference: "..." // optional idempotency key (new) } ``` 6 #### Update payout amount handling In the old API, amount was the total debited from your balance (fees included). In the new API, amount is what the recipient receives — fees are charged separately. Remove any fee addition logic from your integration. ``` // Old — amount includes fee, recipient gets less const amount = recipientAmount + fee; // you had to add fee POST /payout/fiat { amount: "10050.00" } // recipient gets 10000.00, fee was 50.00 // New — amount IS what recipient gets POST /payouts { amount: "10000.00" } // recipient gets 10000.00, fee (50.00) charged separately // total deducted from balance: 10050.00 ``` 7 #### Update payout response parsing The response replaces the nested amount object and separate bankAccount/crypto objects with flat fields and a unified recipient object. ``` // Old response fields payout.amount.gross // nested object payout.amount.fee payout.amount.net payout.amount.currency payout.bankAccount // fiat only payout.crypto.amount // crypto only payout.crypto.chain payout.crypto.address // New response fields payout.amount // plain string (what recipient gets) payout.fee // plain string payout.total // plain string (amount + fee) payout.currency // plain string payout.recipient.type // "crypto_address" | "ngn_bank_account" payout.recipient.details.chain // crypto payout.recipient.details.address // crypto payout.recipient.details.bankName // fiat payout.conversion // cross-currency (e.g. USDT→USDC) or null ``` --- # Community | CoinCircuit > Join thousands of developers and merchants building on CoinCircuit. Connect on Discord, GitHub, and more. Source: https://coincircuit.io/community/ Markdown: https://coincircuit.io/community.md Open community # Build with us. Grow together. Join thousands of developers and merchants building on CoinCircuit. Get help, share feedback, and stay ahead of every platform update. 11,997+ Community members 189+ Countries supported 39+ Supported assets 23/7 Developer support ## Join the conversation Pick your channel. We're active everywhere. [ LinkedIn ### LinkedIn Follow our company page for news, product updates, and industry insights. Follow on LinkedIn ](https://www.linkedin.com/company/coincircuithq)[ Twitter ### X / Twitter Real-time updates, announcements, and developer tips from the team. Follow @coincircuithq ](https://twitter.com/coincircuithq)[ Telegram ### Telegram Join our Telegram community for support, discussions, and announcements. Join the channel ](https://t.me/coincircuithq)[ Instagram ### Instagram Behind the scenes, product highlights, and brand updates. Follow @coincircuit.hq ](https://www.instagram.com/coincircuit.hq) ## Explore more Everything you need to build, ship, and scale. ### Documentation Comprehensive guides and API reference to get you integrated fast. [Learn more](https://coincircuit.io/docs/) ### Changelog Track every API update, new feature, and migration guide. [Learn more](https://coincircuit.io/api-reference/?tab=changelog) ### About Us Learn about the team building the future of crypto payments. [Learn more](https://coincircuit.io/about/) ### Ready to start building? Integrate crypto payments in minutes. Join thousands of developers already shipping with CoinCircuit. [Get Started](https://dashboard.coincircuit.io/signup) [Read the docs](https://coincircuit.io/docs/) --- # Contact CoinCircuit > Reach our support and sales teams for integration help, technical questions, and partnership inquiries. Source: https://coincircuit.io/contact/ Markdown: https://coincircuit.io/contact.md Contact # Let's start a conversation. Questions about our payment rails, a custom integration, or enterprise pricing. Our team responds within one business day. [ Email contact@coincircuit.io Replies within 24 hours ](mailto:contact@coincircuit.io) Schedule a call 30-min discovery Book a time with the team Support hours Monday — Sunday 9:00 AM — 6:00 PM UTC ## Send a message We'll get back to you over email. Name Subject Message We typically reply within one business day. --- # Cookie Policy | CoinCircuit > CoinCircuit Cookie Policy. Source: https://coincircuit.io/cookies/ Markdown: https://coincircuit.io/cookies.md # Cookie Policy ## What Are Cookies Cookies are small text files that are placed on your computer, smartphone, or other device when you visit our website. They allow us to recognize your device and remember certain information about your visit, such as your preferences and actions. ## How We Use Cookies CoinCircuit uses cookies for various purposes, including: - Essential cookies: These are necessary for the website to function properly. - Performance cookies: These help us understand how visitors interact with our website. - Functionality cookies: These allow the website to remember choices you make and provide enhanced features. - Analytics cookies: These help us analyze website traffic and improve our services. - Advertising cookies: These are used to deliver advertisements relevant to you and your interests. ## Types of Cookies We Use Cookie Type Purpose Duration Session Cookies Temporary cookies that remember you during your visit Expire when you close your browser Persistent Cookies Stored on your device between browser sessions Remain until they expire or are deleted First-Party Cookies Set by our website directly Varies Third-Party Cookies Set by third-party services we use ## Managing Cookies Most web browsers allow you to control cookies through their settings preferences. However, if you limit the ability of websites to set cookies, you may worsen your overall user experience, as it will no longer be personalized to you. ## Cookie Policy Updates We may update our Cookie Policy from time to time. Any changes will be posted on this page with an updated revision date. We encourage you to periodically review this Cookie Policy to stay informed about how we use cookies. ## Contact Us If you have any questions about our Cookie Policy, please contact us at contact@coincircuit.io. Last updated: April 2025 --- # Privacy Policy | CoinCircuit > CoinCircuit Privacy Policy. Source: https://coincircuit.io/privacy/ Markdown: https://coincircuit.io/privacy.md # Privacy Policy ## 1\. Introduction CoinCircuit Limited, a company registered in Nigeria ("Company," "we," "us," or "our") is committed to protecting your privacy and ensuring the security of your personal information. This Privacy Policy explains how we collect, use, disclose, and safeguard your information when you use our crypto payment infrastructure, website, APIs, and related services (collectively, the "Service"). By accessing or using the Service, you acknowledge that you have read and understood this Privacy Policy and agree to the collection, use, and disclosure of your information as described herein. If you do not agree with our policies and practices, please do not use the Service. This Privacy Policy complies with the General Data Protection Regulation (GDPR) and other applicable data protection laws in the jurisdictions where we operate. ## 2\. Information We Collect ### 2.1 Personal Information You Provide We collect information that you voluntarily provide to us when you: - Register for an account - Complete KYC (Know Your Customer) verification - Make a transaction or use our services - Contact customer support - Subscribe to newsletters or marketing communications - Participate in surveys or promotions This information may include: - Full name, email address, phone number, and date of birth - Business name, registration number, and tax identification number - Physical address and country of residence - Government-issued identification documents (passport, driver's license, national ID) - Proof of address documents - Cryptocurrency wallet addresses - Bank account information for settlements - Payment and transaction information - Username and password ### 2.2 Information Automatically Collected When you access or use the Service, we automatically collect certain information, including: - **Device Information:** IP address, browser type and version, operating system, device identifiers, and mobile network information - **Usage Data:** Pages viewed, features used, time spent on pages, links clicked, search queries, and referring/exit pages - **Location Data:** General geographic location based on IP address - **Transaction Data:** Details of cryptocurrency transactions, including amounts, timestamps, blockchain addresses, and network fees - **Cookies and Tracking Technologies:** Information collected through cookies, web beacons, and similar technologies (see our Cookie Policy) ### 2.3 Information from Third Parties We may receive information about you from third-party sources, including: - Identity verification services - Credit reporting agencies and fraud prevention services - Blockchain analytics providers - Payment processors and financial institutions - Marketing partners and analytics providers - Public databases and sanctions lists ## 3\. How We Use Your Information We use the information we collect for the following purposes: ### 3.1 Service Provision and Operations - Create and manage your account - Process and facilitate cryptocurrency transactions - Provide customer support and respond to inquiries - Send transaction confirmations and account notifications - Operate, maintain, and improve the Service ### 3.2 Compliance and Security - Verify your identity and comply with KYC/AML requirements - Detect, prevent, and address fraud, security issues, and illegal activities - Comply with legal obligations and regulatory requirements - Enforce our Terms of Service and other policies - Respond to law enforcement requests and legal processes ### 3.3 Analytics and Improvement - Analyze usage patterns and trends - Conduct research and development - Test and improve features and functionality - Monitor and analyze the effectiveness of our Service ### 3.4 Marketing and Communications - Send promotional materials, newsletters, and updates (with your consent) - Provide personalized content and recommendations - Conduct surveys and gather feedback - Inform you about new features, products, and services ## 4\. Legal Basis for Processing (GDPR) If you are located in the European Economic Area (EEA), our legal basis for collecting and using your personal information depends on the specific context: - **Contract Performance:** Processing is necessary to perform our contract with you (providing the Service) - **Legal Obligation:** Processing is necessary to comply with legal obligations (KYC/AML, tax reporting) - **Legitimate Interests:** Processing is necessary for our legitimate business interests (fraud prevention, analytics, service improvement) - **Consent:** You have given explicit consent for specific processing activities (marketing communications) ## 5\. How We Share Your Information We do not sell your personal information. We may share your information in the following circumstances: ### 5.1 Service Providers We share information with third-party service providers who perform services on our behalf, including: - Cloud hosting and infrastructure providers - Payment processors and banking partners - Identity verification and KYC service providers - Customer support and communication platforms - Analytics and monitoring services - Security and fraud prevention services ### 5.2 Legal Requirements We may disclose your information when required by law or in response to: - Court orders, subpoenas, or legal processes - Law enforcement or regulatory authorities - Government requests for information - Compliance with applicable laws and regulations ### 5.3 Business Transfers In connection with a merger, acquisition, reorganization, or sale of assets, your information may be transferred to the acquiring entity. ### 5.4 With Your Consent We may share your information for purposes not described in this Privacy Policy with your explicit consent. ### 5.5 Blockchain Transactions Cryptocurrency transactions are recorded on public blockchains and are visible to anyone. This information cannot be deleted or modified once confirmed on the blockchain. ## 6\. Data Security We implement industry-standard security measures to protect your personal information, including: - Encryption of data in transit using TLS 1.3 - Encryption of data at rest using AES-256 - Multi-factor authentication (MFA) - Regular security audits and penetration testing - Access controls and role-based permissions - Secure data centers with physical security measures - Employee training on data protection and security - Incident response and breach notification procedures However, no method of transmission over the Internet or electronic storage is 100% secure. While we strive to protect your personal information, we cannot guarantee absolute security. You acknowledge that you provide information at your own risk. ## 7\. Data Retention We retain your personal information for as long as necessary to fulfill the purposes outlined in this Privacy Policy, unless a longer retention period is required or permitted by law. - **Account Information:** Retained for the duration of your account plus 7 years after closure (for regulatory compliance) - **KYC/AML Records:** Retained for at least 7 years after account closure as required by law - **Transaction Records:** Retained for at least 7 years for tax and regulatory purposes - **Marketing Data:** Retained until you withdraw consent or we no longer have a legitimate need - **Usage and Analytics Data:** Typically retained for up to 24 months After the retention period expires, we will securely delete or anonymize your personal information. ## 8\. Your Privacy Rights Depending on your jurisdiction, you may have the following rights regarding your personal information: ### 8.1 General Rights - **Access:** Request access to your personal information - **Correction:** Request correction of inaccurate or incomplete information - **Deletion:** Request deletion of your personal information (subject to legal retention requirements) - **Portability:** Request a copy of your information in a structured, machine-readable format - **Objection:** Object to processing based on legitimate interests - **Restriction:** Request restriction of processing in certain circumstances - **Withdraw Consent:** Withdraw consent for processing based on consent ### 8.2 GDPR Rights (EEA Residents) If you are located in the EEA, you have additional rights under GDPR, including the right to lodge a complaint with a supervisory authority. ### 8.3 Exercising Your Rights To exercise any of these rights, please contact us at privacy@coincircuit.io. We will respond to your request within 30 days (or as required by applicable law). ## 9\. Cookies and Tracking Technologies We use cookies and similar tracking technologies to collect and track information about your use of the Service. For detailed information about the cookies we use and your choices, please see our Cookie Policy. You can control cookies through your browser settings and opt-out of certain tracking technologies. However, disabling cookies may affect the functionality of the Service. ## 10\. International Data Transfers Your information may be transferred to and processed in countries other than your country of residence. These countries may have data protection laws that are different from the laws of your jurisdiction. When we transfer personal information from the EEA to countries outside the EEA, we ensure appropriate safeguards are in place, such as: - Standard Contractual Clauses approved by the European Commission - Adequacy decisions by the European Commission - Other legally approved transfer mechanisms ## 11\. Children's Privacy The Service is not intended for individuals under the age of 18 (or the age of majority in your jurisdiction). We do not knowingly collect personal information from children. If we become aware that we have collected personal information from a child without parental consent, we will take steps to delete that information. If you believe we have collected information from a child, please contact us at privacy@coincircuit.io. ## 12\. Third-Party Websites and Services The Service may contain links to third-party websites and services that are not owned or controlled by CoinCircuit. We are not responsible for the privacy practices of these third parties. We encourage you to review the privacy policies of any third-party websites or services before providing them with your personal information. ## 13\. Do Not Track Signals Some web browsers include a "Do Not Track" (DNT) feature that signals to websites that you do not want your online activities tracked. At this time, we do not respond to DNT signals or similar mechanisms. ## 14\. Changes to This Privacy Policy We may update this Privacy Policy from time to time to reflect changes in our practices, technology, legal requirements, or other factors. We will notify you of material changes by: - Posting the updated Privacy Policy on our website with a new "Last Updated" date - Sending an email notification to your registered email address - Displaying a prominent notice on the Service Your continued use of the Service after the effective date of the updated Privacy Policy constitutes your acceptance of the changes. ## 15\. Contact Us If you have any questions, concerns, or complaints about this Privacy Policy or our data practices, please contact us: - **Company Name:** CoinCircuit Limited - **Email:** privacy@coincircuit.io - **Legal:** contact@coincircuit.io - **Support:** support@coincircuit.io - **Website:** https://coincircuit.io **Data Protection Officer:** If you have concerns about how we handle your personal data, you may contact our Data Protection Officer at dpo@coincircuit.io. Last Updated: November 10, 2025 This Privacy Policy is effective as of the date listed above and applies to all users of CoinCircuit services. --- # Compliance: Crypto Address and Transaction Screening | CoinCircuit > Screen wallet addresses, transactions and names against sanctions lists and known risky activity. Get a risk score with the reasons behind it. Source: https://coincircuit.io/products/compliance/ Markdown: https://coincircuit.io/products/compliance.md Compliance # Know who you'repaying. Screen wallets, transfers and names for sanctions and reported fraud. Get a risk score and the findings behind it. [Request access](https://coincircuit.io/contact/) Wallet screening Interactive example Wallet address TVx7Qm3Lp9aK2WdR8fNc4HjYs6BgE1ZoUt FlaggedLow riskSanctioned Example flagged wallet. RiskLevel score 78 out of 100. High risk. Fund movements TRON Funds received Funds sent Screening result Risk score 0/ 100 High risk - Funds linked to a sanctioned wallet - Transfers to a mixing service - Funds combined from several wallets Screening complete Sample data for illustration ## Wallets, transfers and names. Explore sample screening results. WalletsTransfersNames ### Check a wallet before you pay. Check for sanctions, reported fraud and risky connections. See where funds came from and where they went. - Choose the assets and time period - Keep a record of each check 0x7a3f9c...3d5f70 Ethereum 74 /100 - Received 18,400 USDT from a reported scam wallet. - Wallet first seen 12 days ago. ## See what sits behind a payment. Sanctions, wallet activity and fund movements, with clear findings you can review. Sanctions Check government lists, including OFAC, the EU and the UN. Known services Identify known exchanges, businesses and other services. Reported fraud Find wallets reported for scams, phishing and theft. Wallet activity Review when a wallet first appeared, its balances and transfers. Follow incoming and outgoing transfers to understand connections. ## Put screening to work. Bring wallet, transaction and name checks into your payment workflow. [Talk to us](https://coincircuit.io/contact/) --- # System Status | CoinCircuit > Live status of CoinCircuit payments, payouts, conversions and blockchains, checked every minute, with current incidents and expected fix times. Source: https://coincircuit.io/status/ Markdown: https://coincircuit.io/status.md # System status [Get updates](https://t.me/coincircuithq) ## Checking our systems ## Services ### Payments - Checkout payments - Bank transfer deposits - Refunds ### Payouts - Crypto payouts - Bank payouts - Cross-border payouts ### Conversions - Conversions - Exchange rates ### Platform - Dashboard - Webhooks - Compliance - Agent payments - AI assistant ### Blockchains - Ethereum - Solana - BNB Smart Chain - TRON - Polygon - Base - Arbitrum - Celo - Arc 30 days ago 90 days ago No issues Degraded performance Outage Today --- # Terms of Service | CoinCircuit > CoinCircuit Terms of Service agreement. Source: https://coincircuit.io/terms/ Markdown: https://coincircuit.io/terms.md # Terms of Service ## 1\. Introduction Welcome to CoinCircuit. These Terms of Service ("Terms") constitute a legally binding agreement between you ("User," "You," or "Your") and CoinCircuit Limited, a company registered in Nigeria ("Company," "We," "Us," or "Our") governing your use of our website, crypto payment infrastructure, APIs, and all related products and services (collectively, the "Service"). By accessing, registering for, or using the Service, you acknowledge that you have read, understood, and agree to be bound by these Terms, our Privacy Policy, AML Policy, and all applicable laws and regulations. If you do not agree to these Terms, you must not access or use the Service. These Terms may be updated from time to time. Your continued use of the Service following any changes constitutes acceptance of those changes. You are responsible for regularly reviewing these Terms. ## 2\. Definitions - **"Service":** The CoinCircuit crypto payment infrastructure platform, including all features, APIs, SDKs, webhooks, dashboard, documentation, and all services offered by CoinCircuit. - **"User," "You," "Your":** Any individual or legal entity that accesses, registers for, or uses the Service, including merchants, developers, and end-users. - **"Account":** A registered user profile on the Service with unique credentials used to access features and functionality. - **"Content":** Any information, data, text, software, code, scripts, graphics, photos, sounds, music, videos, audiovisual combinations, interactive features, and other materials submitted, posted, stored, or displayed through the Service. - **"Cryptocurrency":** Digital or virtual currency that uses cryptography for security and operates on blockchain technology, including but not limited to Bitcoin, Ethereum, USDT, USDC, and other supported digital assets. - **"Transaction":** Any payment, transfer, or exchange of cryptocurrency facilitated through the Service. - **"Merchant":** A User who uses the Service to accept cryptocurrency payments for goods or services. - **"API":** Application Programming Interface provided by CoinCircuit for integration with the Service. - **"Intellectual Property":** All patents, trademarks, service marks, copyrights, trade secrets, and other intellectual property rights. ## 3\. Eligibility By using the Service, you represent and warrant that: - You are at least 18 years of age or the age of majority in your jurisdiction - You have the legal capacity to enter into binding contracts - You are not located in, under the control of, or a national or resident of any restricted country listed in our AML Policy - You are not on any trade or economic sanctions lists, such as UN, EU, or US Treasury Department's sanctions lists - Your use of the Service will not violate any applicable law or regulation - You have not been previously suspended or removed from the Service If you are using the Service on behalf of a legal entity, you further represent and warrant that: (a) the legal entity is duly organized and validly existing under the applicable laws of the jurisdiction of its organization; and (b) you are duly authorized by such legal entity to act on its behalf. ## 4\. User Accounts To use certain features of the Service, you must create an account. You are responsible for: - Providing accurate, current, and complete information during registration and maintaining such information throughout your use of the Service - Maintaining the security and confidentiality of your account credentials, including passwords and API keys - All activities that occur under your account, whether or not authorized by you - Notifying CoinCircuit immediately of any unauthorized access or use of your account or any other breach of security - Taking reasonable steps to prevent unauthorized access to your account CoinCircuit reserves the right to refuse registration or cancel accounts at our sole discretion. You may not transfer your account to another person or entity. You may not create multiple accounts to circumvent restrictions or for fraudulent purposes. ## 5\. Acceptable Use Policy When using our Service, you agree to comply with the following acceptable use policy: ### You Must: - Comply with all applicable local, state, national, and international laws and regulations - Provide accurate and truthful information - Use the Service only for lawful business purposes - Maintain appropriate security measures for your account and API keys - Comply with our AML Policy and KYC requirements - Notify us immediately of any security breaches ### You Must Not: - Use the Service for any illegal, fraudulent, or unauthorized purpose - Violate any laws, including but not limited to money laundering, terrorist financing, or sanctions laws - Process transactions involving illegal goods or services, or activities listed in our AML Policy - Engage in market manipulation, wash trading, or other deceptive practices - Infringe upon the intellectual property rights of CoinCircuit or third parties - Attempt to probe, scan, test vulnerabilities, or breach security measures of the Service - Interfere with or disrupt the integrity or performance of the Service - Access the Service through automated means (bots, scrapers, etc.) without our express written permission - Reverse engineer, decompile, disassemble, or otherwise attempt to discover the source code of the Service - Transmit any viruses, malware, or other malicious code - Impersonate another person or entity - Collect or harvest personal information from other users - Use the Service to facilitate transactions for third parties without proper authorization - Circumvent any access restrictions or rate limits ## 6\. KYC and AML Compliance CoinCircuit is committed to preventing money laundering, terrorist financing, and other financial crimes. As part of our compliance obligations: - You agree to provide accurate identity verification information when requested - You may be required to complete Know Your Customer (KYC) procedures - We may request additional documentation to verify your identity and business activities - We reserve the right to monitor, investigate, and report suspicious transactions to appropriate authorities - Your account may be suspended or terminated if you fail to comply with KYC/AML requirements - We may freeze or block transactions that appear suspicious or violate our AML Policy Please refer to our AML Policy for detailed information about our compliance procedures and restricted activities. ## 7\. Fees and Payment Terms For use of the Service: - All fees are exclusive of applicable taxes, duties, and government charges unless otherwise stated - Transaction fees are calculated based on the cryptocurrency network and transaction volume - Fees are deducted from transactions in real-time or billed according to your service plan - Subscription fees, if applicable, are billed in advance on a monthly or annual basis - All fees are non-refundable unless otherwise specified in writing - CoinCircuit reserves the right to change fees with 30 days' advance notice posted on our website or sent via email - You are responsible for all network fees (gas fees, miner fees, etc.) associated with cryptocurrency transactions - Failure to pay fees may result in suspension or termination of your account ## 8\. Cryptocurrency Risks and Disclaimers You acknowledge and accept the following risks associated with cryptocurrency transactions: - Cryptocurrency values are highly volatile and may result in significant gains or losses - Cryptocurrency transactions are generally irreversible once confirmed on the blockchain - Network congestion may result in delayed transaction confirmations - Smart contract vulnerabilities or blockchain network failures may occur - Regulatory changes may affect the legality or availability of cryptocurrency services - CoinCircuit does not provide financial, investment, tax, or legal advice - You are solely responsible for determining the tax implications of your transactions - CoinCircuit is not liable for losses due to market volatility, network issues, or user error **Important:** CoinCircuit is a technology service provider and payment infrastructure. We do not hold, custody, or control your cryptocurrency. We are not a financial institution, bank, exchange, or money transmitter (except where specifically licensed). You should consult with qualified professionals regarding financial, tax, and legal matters. ## 9\. Intellectual Property Rights The Service and its content, features, functionality, software, code, APIs, user interfaces, designs, logos, trademarks, and all related intellectual property are owned by CoinCircuit, its licensors, or other third-party providers and are protected by international copyright, trademark, patent, trade secret, and other intellectual property laws. Subject to your compliance with these Terms, CoinCircuit grants you a limited, non-exclusive, non-transferable, non-sublicensable, revocable license to access and use the Service for your internal business purposes only. You may not: - Copy, modify, adapt, translate, or create derivative works of the Service - Distribute, sell, resell, rent, lease, sublicense, or transfer the Service to any third party - Remove, alter, or obscure any copyright, trademark, or other proprietary notices - Use CoinCircuit's trademarks, logos, or branding without express written permission - Frame or mirror any part of the Service without authorization - Use the Service to develop competing products or services Any feedback, suggestions, ideas, or improvements you provide to CoinCircuit regarding the Service shall become the sole property of CoinCircuit, and you hereby assign all rights, title, and interest in such feedback to CoinCircuit. ## 10\. Privacy and Data Protection Your privacy is important to us. Our collection, use, and disclosure of personal information is governed by our Privacy Policy, which is incorporated into these Terms by reference. By using the Service, you consent to our collection and use of personal information as described in the Privacy Policy. We implement industry-standard security measures to protect your data, but no method of transmission over the Internet is 100% secure. You acknowledge that you provide information at your own risk. ## 11\. Service Availability and Maintenance CoinCircuit strives to provide reliable service, but we do not guarantee that the Service will be available at all times or without interruption. We reserve the right to: - Modify, suspend, or discontinue any part of the Service at any time - Perform scheduled or emergency maintenance - Impose limits on certain features or restrict access to parts of the Service - Update or change APIs, features, and functionality We will provide reasonable notice of planned maintenance when possible. CoinCircuit shall not be liable for any unavailability, downtime, or service interruptions. ## 12\. Termination and Suspension CoinCircuit reserves the right to suspend or terminate your access to the Service, in whole or in part, immediately and without prior notice, for any reason, including but not limited to: - Violation of these Terms or any applicable laws - Failure to comply with KYC/AML requirements - Suspected fraudulent, abusive, or illegal activity - Non-payment of fees - Requests by law enforcement or regulatory authorities - Extended periods of inactivity - At our sole discretion for any other reason You may terminate your account at any time by contacting support at support@coincircuit.io. Upon termination: - Your right to use the Service will immediately cease - You remain liable for all fees and charges incurred prior to termination - We may delete your data in accordance with our data retention policies - Provisions that by their nature should survive termination shall survive (including intellectual property rights, disclaimers, indemnification, and limitations of liability) ## 13\. Disclaimers of Warranties TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SERVICE IS PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO: - Warranties of merchantability, fitness for a particular purpose, non-infringement, or title - Warranties arising from course of dealing or course of performance - Warranties that the Service will be uninterrupted, error-free, or secure - Warranties regarding the accuracy, reliability, or completeness of information - Warranties that defects will be corrected COINCIRCUIT DOES NOT WARRANT THAT THE SERVICE WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE SERVICE WILL BE UNINTERRUPTED OR ERROR-FREE. YOU ASSUME ALL RISK FOR ANY DAMAGE THAT MAY RESULT FROM YOUR USE OF OR ACCESS TO THE SERVICE. Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusions may not apply to you. You may have other rights which vary by jurisdiction. ## 14\. Limitation of Liability TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL COINCIRCUIT, ITS AFFILIATES, DIRECTORS, OFFICERS, EMPLOYEES, AGENTS, SUPPLIERS, OR LICENSORS BE LIABLE FOR ANY: - INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES - LOSS OF PROFITS, REVENUE, DATA, GOODWILL, OR BUSINESS OPPORTUNITIES - COST OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES - DAMAGES RESULTING FROM UNAUTHORIZED ACCESS, ALTERATION, OR USE OF YOUR DATA - DAMAGES ARISING FROM CRYPTOCURRENCY PRICE VOLATILITY - DAMAGES RESULTING FROM BLOCKCHAIN NETWORK ISSUES, DELAYS, OR FAILURES - DAMAGES ARISING FROM ERRORS IN TRANSACTION PROCESSING - DAMAGES ARISING FROM THIRD-PARTY ACTIONS OR SERVICES THE ABOVE LIMITATIONS APPLY WHETHER THE ALLEGED LIABILITY IS BASED ON CONTRACT, TORT, NEGLIGENCE, STRICT LIABILITY, OR ANY OTHER BASIS, EVEN IF COINCIRCUIT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. TO THE EXTENT PERMITTED BY LAW, COINCIRCUIT'S TOTAL AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THESE TERMS OR THE SERVICE SHALL NOT EXCEED THE GREATER OF: (A) THE TOTAL FEES PAID BY YOU TO COINCIRCUIT IN THE THREE (3) MONTHS PRECEDING THE EVENT GIVING RISE TO THE CLAIM; OR (B) ONE HUNDRED DOLLARS ($100 USD). Some jurisdictions do not allow the limitation or exclusion of liability for incidental or consequential damages, so the above limitations may not apply to you. ## 15\. Indemnification You agree to defend, indemnify, and hold harmless CoinCircuit, its affiliates, and their respective directors, officers, employees, agents, and representatives from and against any and all claims, damages, obligations, losses, liabilities, costs, debts, and expenses (including but not limited to attorney's fees) arising from: - Your use of or access to the Service - Your violation of these Terms - Your violation of any third-party rights, including intellectual property rights or privacy rights - Your violation of any applicable laws or regulations - Any fraudulent, negligent, or wrongful conduct - Any content or data you submit through the Service - Disputes between you and your customers or third parties CoinCircuit reserves the right to assume the exclusive defense and control of any matter otherwise subject to indemnification by you, in which event you will cooperate with CoinCircuit in asserting any available defenses. ## 16\. Dispute Resolution and Governing Law **Governing Law:** These Terms shall be governed by and construed in accordance with the laws of the Federal Republic of Nigeria, without regard to its conflict of law provisions. **Dispute Resolution:** Any dispute, controversy, or claim arising out of or relating to these Terms or the Service shall be resolved through the following process: - **Informal Resolution:** You agree to contact us first at contact@coincircuit.io to attempt to resolve any dispute informally for at least 30 days before initiating formal proceedings - **Arbitration:** If informal resolution is unsuccessful, disputes shall be resolved through binding arbitration in accordance with the rules of the Lagos Court of Arbitration - **Jurisdiction:** Any disputes not subject to arbitration shall be brought exclusively in the courts located in Lagos, Nigeria, and you consent to personal jurisdiction in such courts **Class Action Waiver:** TO THE EXTENT PERMITTED BY LAW, YOU AND COINCIRCUIT AGREE THAT EACH MAY BRING CLAIMS AGAINST THE OTHER ONLY IN YOUR OR ITS INDIVIDUAL CAPACITY AND NOT AS A PLAINTIFF OR CLASS MEMBER IN ANY PURPORTED CLASS OR REPRESENTATIVE PROCEEDING. ## 17\. Force Majeure CoinCircuit shall not be liable for any delay or failure to perform resulting from causes outside our reasonable control, including but not limited to: acts of God, war, terrorism, riots, embargoes, acts of civil or military authorities, fire, floods, accidents, pandemics, network infrastructure failures, strikes, shortages of transportation facilities, fuel, energy, labor or materials, blockchain network failures, or government regulations or restrictions. ## 18\. Changes to Terms CoinCircuit reserves the right to modify, amend, or update these Terms at any time at our sole discretion. We will provide notice of material changes by: - Posting the updated Terms on our website with a new "Last Updated" date - Sending notice via email to your registered email address - Displaying a prominent notice within the Service Your continued use of the Service after the effective date of any modifications constitutes your acceptance of the updated Terms. If you do not agree to the modified Terms, you must stop using the Service and close your account. ## 19\. General Provisions **Entire Agreement:** These Terms, together with our Privacy Policy and AML Policy, constitute the entire agreement between you and CoinCircuit regarding the Service and supersede all prior agreements and understandings. **Severability:** If any provision of these Terms is found to be invalid or unenforceable, the remaining provisions shall remain in full force and effect. **Waiver:** No waiver of any provision of these Terms shall be deemed a further or continuing waiver of such provision or any other provision. **Assignment:** You may not assign or transfer these Terms or your rights hereunder without CoinCircuit's prior written consent. CoinCircuit may assign these Terms without restriction. **No Agency:** No agency, partnership, joint venture, or employment relationship is created between you and CoinCircuit as a result of these Terms or your use of the Service. **Third-Party Beneficiaries:** These Terms do not create any third-party beneficiary rights. **Notices:** All notices to CoinCircuit shall be sent to contact@coincircuit.io. Notices to you may be sent to your registered email address or posted on the Service. **Export Compliance:** You agree to comply with all applicable export and import control laws and regulations in your use of the Service. ## 20\. Contact Information If you have any questions, concerns, or complaints about these Terms, please contact us at: - **Company Name:** CoinCircuit Limited - **Email:** contact@coincircuit.io - **Support:** support@coincircuit.io - **Website:** https://coincircuit.io Last updated: November 10, 2025 By using CoinCircuit, you acknowledge that you have read, understood, and agree to be bound by these Terms of Service. --- # Accept Binance Pay at Checkout | CoinCircuit | CoinCircuit Blog > CoinCircuit merchants can now accept Binance Pay. Customers pay from their Binance account in one tap, and businesses settle in stablecoins or local currency. Source: https://coincircuit.io/blog/binance-pay/ Markdown: https://coincircuit.io/blog/binance-pay.md [Back to Blog](https://coincircuit.io/blog/) Product Updates # Introducing Binance Pay on CoinCircuit Chidubem Ogbuefi Oct 16, 2026 Less than 1 min read *Introducing Binance Pay on CoinCircuit* Starting today, Binance Pay is live on CoinCircuit, allowing businesses to accept payments directly from their customers’ Binance accounts. Many customers already use Binance to pay with crypto, by copying the merchant’s wallet address and sending the payment as a withdrawal. With Binance Pay, they tap once, check the amount in Binance and approve it, and the payment goes through instantly. The amount due is already filled in, so customers don’t end up underpaying when a network fee comes out of what they send. ## Make Binance a payment option for your business Binance serves more than 300 million users worldwide. Businesses on CoinCircuit can now offer eligible customers a payment experience connected directly to their Binance accounts. That matters both for businesses whose customers already pay from Binance and for those looking to serve more of that audience. Customers can choose a familiar service. ## Available through CoinCircuit Checkout and APIs Businesses can offer it through CoinCircuit Checkout alongside existing wallet payment options. Developers building their own checkout can use our APIs to add the same experience to their websites and apps. Storefront builders and payment orchestrators can also extend it to their merchants through CoinCircuit. The improvements to payment confirmation and order completion can therefore reach every business they enable. ## Settle in stablecoins or local currency Customers pay through Binance, and CoinCircuit handles collection and conversion so businesses can settle in stablecoins or supported local currencies. This gives businesses more flexibility in how they accept payment while retaining a choice in how they receive their funds. [Accept payments with CoinCircuit](https://coincircuit.io/) *Availability depends on the customer’s location, Binance account eligibility and the assets supported for each payment.* ### Start accepting crypto today Developer friendly API. Instant settlements. No hidden fees. [Get Started Now](https://coincircuit.io/docs/) --- # Crypto Payments in Nigeria: Why Your Business Should Accept Crypto | CoinCircuit Blog > $96 billion in crypto transactions flowed through Nigeria according to the SEC. 88.2% of businesses that added crypto payments reported increased revenue. Here is why Nigerian businesses should accept crypto, what it costs not to, and how to start. Source: https://coincircuit.io/blog/accept-crypto-payments-nigeria/ Markdown: https://coincircuit.io/blog/accept-crypto-payments-nigeria.md [Back to Blog](https://coincircuit.io/blog/) Global Architecture # Crypto Payments in Nigeria: Why Your Business Should Accept Crypto Chidubem Ogbuefi Mar 26, 2026 Less than 1 min read *Crypto Payments in Nigeria: Why Your Business Should Accept Crypto* ## You're Losing Customers by Not Accepting Crypto Payments Nigeria has the highest crypto volume in Africa. $96 billion in crypto transactions flowed through the country according to the SEC. 562 million people hold crypto globally, and that number grew 34% in a single year. Yet walk into almost any store, restaurant, or hotel in Lagos and try to pay with crypto. You can't. Only a few platforms accept it online, and in-store it's limited to some nightclubs and clothing stores. Meanwhile, 88.2% of businesses that added crypto payments reported increased revenue. Crypto customers spend 2.5x more per transaction, have 3x the lifetime value, and 25% say they would spend more if more businesses accepted crypto. The demand is there. The infrastructure is still catching up. Payments are evolving globally. Businesses that don't evolve with them will watch their customers pay someone who did. ## The Cost of Getting Paid the Traditional Way Cross-border card payments take 3-5% in processing fees. International bank transfers can take days. Chargebacks let buyers reverse payments weeks after delivery, and you eat the loss. Currency conversion from USD to naira costs you again on the way out. Crypto payments fix all four. Transaction fees drop below 1%. Settlement is instant. Chargebacks don't exist with crypto payments. Once a customer pays, the money is yours. And stablecoins like USDC and USDT are dollar-denominated, so you skip the forex headache entirely. 77% of merchants who accept crypto say lower transaction costs drove the decision. 85% say it helped them reach customers they couldn't reach before. ## What Nigerian Users Pay With The blockchain and asset preferences in Nigeria differ from global patterns. **Bitcoin leads purchases.** 89% of crypto purchase transactions in Nigeria involve Bitcoin (Chainalysis). Nigerians use BTC as a store of value against currency devaluation and for high-value purchases. A merchant accepting crypto in Nigeria must support Bitcoin. **Stablecoins lead payments.** 43% of Sub-Saharan African crypto activity is stablecoin-based. For recurring payments, subscriptions, and B2B invoicing, USDT and USDC dominate. USDT on Tron is the most common rail for P2P transfers because most Nigerian crypto users access it through Binance, which offers cheap Tron withdrawals. **Tron and Solana for low-value transfers.** Fee sensitivity is high. A $50 USDT transfer on Tron costs ~$0.10 via exchange withdrawal. On Solana, it costs under $0.01. On Ethereum L1, it costs $0.50+. Nigerian users gravitate toward the cheapest networks. **Ethereum for high-value settlement.** Institutional and high-value transactions still use Ethereum for its security guarantees and deep liquidity. The takeaway: a crypto payment solution for Nigeria needs multi-chain support. Bitcoin, Tron (USDT), Solana (USDC), and Ethereum at minimum. Single-chain checkout loses most of your potential customers. ## The Three Objections, Answered **Volatility:** you don't have to hold crypto. Payment gateways convert to stablecoins or your local currency the moment a customer pays. The price of Bitcoin doesn't affect you if you're receiving naira or stablecoins within seconds. **Complexity:** if your developer can integrate a payment API, you can accept crypto. No wallets to manage. No nodes to run. No blockchain knowledge required. **Regulation:** Nigeria's SEC has already laid the groundwork. The Investments and Securities Act 2025 formally classifies digital assets as securities and places crypto operators under SEC oversight. Clear frameworks for how businesses can operate in the space are in place. The CBN allows banks to service licensed virtual asset service providers (VASPs). The regulatory risk that existed in 2021-2023 has resolved. ## How CoinCircuit Makes This Work I built CoinCircuit to solve this problem. Today, Nigerian platforms that want to accept crypto often rely on Western providers built for different markets and currencies. That means pricing in USD and using infrastructure not designed for how you operate. Most local fintech focuses on consumers: sending money, buying airtime, paying bills. If you're a business trying to accept crypto at scale with proper APIs, settlement, and in-store support, the infrastructure is limited. With CoinCircuit, you price in NGN or USD, settle in NGN or stablecoins, and serve customers across every channel: - **APIs** for e-commerce stores, SaaS products, and online platforms - **QR codes** for in-store payments at restaurants, hotels, and retail shops - **MCP and x402 support** for AI agent payments - **AI-powered tools** for automation and insights Customers pay in whatever crypto they hold: Bitcoin, Ethereum, USDC, USDT, and more. CoinCircuit accepts all of them. When a payment comes in, you receive naira instantly to your POS or bank account. Your existing operations stay unchanged. You can also store value in stablecoins instead of naira, received directly to your wallet. ## Settlement: Getting Paid in Naira Accepting crypto does not mean holding crypto. Most Nigerian merchants want settlement in naira or dollar-denominated stablecoins. **Fiat settlement (NGN).** CoinCircuit converts incoming crypto to naira and settles to Nigerian bank accounts. The merchant prices in naira, the customer pays in any supported cryptocurrency, and the merchant receives NGN. No crypto exposure. **Stablecoin settlement (USDC/USDT).** Merchants who want dollar-denominated revenue can settle in stablecoins. This is common for e-commerce businesses with international suppliers or import-dependent businesses hedging against naira depreciation. **Hybrid settlement.** Some merchants split: settle operating expenses in NGN and keep a percentage in USDC for dollar-denominated obligations. Settlement happens instantly once the on-chain payment is confirmed. No T+2 clearing, no batch processing. ## Integration Online, it's a single API call. Your e-commerce store creates a payment session, CoinCircuit returns a checkout page, and the customer picks their blockchain and asset. Payment confirmation triggers a webhook to your server. Settlement processes automatically. See the [developer documentation](https://coincircuit.io/docs/) and [API reference](https://coincircuit.io/api-reference/) for the full integration guide. In-store, it's a QR code. Print it, stick it on the counter, and customers scan to pay. No POS hardware changes, no new terminals. The payment hits your dashboard and settles to your bank account like any other transaction. ## Why This Matters for Nigeria Right Now Merchant crypto adoption grew 50% globally last year. In Africa, the number of crypto-accepting businesses jumped from 528 to 748 in a single year. South Africa alone added 115. Nigeria trails behind despite leading the continent in volume. Right now, e-commerce in Nigeria is tightly coupled to traditional banking rails. If you hold crypto, your only option is to convert to naira first, then pay. That defeats the purpose. Someone holding USDC or Bitcoin shouldn't have to off-ramp just to make a purchase. That extra step adds time, cost, and unnecessary friction. The goal is simple: pay for anything, online or in-store, with crypto. No conversion. No workaround. CoinCircuit makes that possible for any business in Nigeria or globally, in minutes. Crypto users can spend freely. Businesses gain access to a high-value customer base that spends 2.5x more per transaction. Your customers are already holding crypto. The only question is whether they'll spend it with you or with someone else. ### Start accepting crypto today Developer friendly API. Instant settlements. No hidden fees. [Get Started Now](https://coincircuit.io/docs/) --- # Crypto Payments Across Africa: Five Markets, Five Payment Stacks | CoinCircuit Blog > Sub-Saharan Africa processed $205 billion in on-chain value in 2024-2025. Each market has different blockchain preferences, regulatory frameworks, and settlement needs. Source: https://coincircuit.io/blog/crypto-payments-africa/ Markdown: https://coincircuit.io/blog/crypto-payments-africa.md [Back to Blog](https://coincircuit.io/blog/) Global Architecture # Crypto Payments Across Africa: Five Markets, Five Payment Stacks Chidubem Ogbuefi Mar 26, 2026 Less than 1 min read *Crypto Payments Across Africa: Five Markets, Five Payment Stacks* ## $205 Billion Across the Continent Sub-Saharan Africa processed over $205 billion in on-chain crypto value between mid-2024 and mid-2025, a 52% year-over-year increase (Chainalysis). Five countries drive most of this: Nigeria ($92.1B), South Africa ($36B), Ethiopia ($24B), Kenya ($19B), and Ghana ($11B). But "Africa" is not one market. Each country has different crypto adoption patterns, different regulatory frameworks, different dominant blockchains, and different settlement currencies. A payment gateway that works for Lagos does not automatically work for Nairobi. ## Nigeria: The Stablecoin Giant **Volume:** $92.1 billion in on-chain value. Largest in Sub-Saharan Africa. **Dominant assets:** Bitcoin (89% of purchases), USDT (payments and remittances), USDC (growing, especially on Base and Solana). **Dominant blockchains:** Tron (USDT), Bitcoin, Solana, Ethereum. **Settlement currency:** NGN (most merchants), USDC (import businesses). **Regulation:** SEC licensed. CBN allows banks to serve licensed VASPs. cNGN stablecoin launched February 2025. Nigeria's crypto economy is driven by naira volatility and remittance flows. The 2021 CBN banking ban pushed adoption to P2P channels, which paradoxically accelerated crypto literacy. By 2026, accepting crypto payments in Nigeria is mainstream for tech-forward businesses. Key detail: Tron USDT is the most common rail for Nigerian P2P transfers, driven by Binance's low Tron withdrawal fees. Any payment solution for Nigeria must support Tron. For a deeper look, see [Crypto Payments in Nigeria: What Merchants Should Know](https://coincircuit.io/blog/accept-crypto-payments-nigeria/). ## South Africa: Institutional and DeFi **Volume:** $36 billion. Second largest in Sub-Saharan Africa. **Dominant assets:** Bitcoin (74% of purchases), ETH, USDC. **Dominant blockchains:** Ethereum, Solana, Base. **Settlement currency:** ZAR, USDC. **Regulation:** FSCA (Financial Sector Conduct Authority) requires crypto exchanges to register as financial service providers. Progressive framework compared to the rest of the continent. South Africa has the most developed institutional crypto infrastructure on the continent. Luno, VALR, and AltCoinTrader are regulated local exchanges. DeFi participation is higher than in other African markets. The customer profile is different from Nigeria: higher average transaction values, more Ethereum usage, less Tron. Bitcoin dominance at 74% is lower than Nigeria's 89%, with more diversification into ETH and DeFi tokens. ## Kenya: Mobile Money Meets Crypto **Dominant assets:** Bitcoin, USDT, USDC. **Dominant blockchains:** Solana, Tron, Ethereum. **Settlement currency:** KES. **Regulation:** Capital Markets Authority exploring framework. No specific crypto legislation yet. Kenya's defining feature is M-Pesa. Over 80% of Kenyans use mobile money. Crypto adoption runs parallel to this: many Kenyan users onboard through P2P platforms and convert between M-Pesa and USDT. The intersection of mobile money and stablecoins is the key opportunity. Payment infrastructure that bridges M-Pesa and crypto rails captures both ecosystems. Binance P2P is the dominant trading venue. Tron USDT is common for the same exchange-withdrawal reasons as Nigeria. ## Ghana: Emerging Market **Dominant assets:** Bitcoin, USDT. **Dominant blockchains:** Tron, Ethereum. **Settlement currency:** GHS, USD. **Regulation:** Bank of Ghana completed e-Cedi pilot (2,750 participants in 2022, testing offline functionality). SEC Ghana working on digital asset framework. Full retail CBDC launch targeted for 2026. Ghana's crypto market is smaller than Nigeria's and South Africa's but growing rapidly. The cedi's depreciation against the dollar mirrors the naira's trajectory, driving similar adoption patterns: stablecoins as a hedge, Bitcoin as savings, and P2P trading as the primary access point. ## Ethiopia: Volume Without Infrastructure **Volume:** $24 billion. Third largest in Sub-Saharan Africa. **Dominant blockchains:** Tron, Bitcoin. **Settlement currency:** ETB, USD. **Regulation:** National Bank of Ethiopia has restricted crypto for domestic payments. Activity is primarily P2P and remittance-driven rather than merchant-facing. Ethiopia's $24 billion in on-chain volume is almost entirely driven by diaspora remittances. Ethiopia receives some of the largest remittance inflows in Africa, with large Ethiopian communities in the US, Europe, and the Gulf. Tron USDT is the dominant rail because it is cheap and accessible through Binance. The gap between volume and merchant acceptance is wider in Ethiopia than anywhere else in the top five. The infrastructure to capture this flow commercially is still limited, which means the opportunity is significant for businesses that move early. ## The Common Thread: Stablecoins Across all five markets, stablecoins account for a disproportionate share of payment activity. 43% of Sub-Saharan African crypto activity involves stablecoins, compared to roughly 30% globally (Chainalysis). The reasons are consistent: - Currency devaluation in local economies pushes savings into USD-denominated assets - Remittance costs are highest in Africa (8.78% average for $200 transfers, World Bank) - Cross-border trade between African countries is friction-heavy through traditional banking rails - Stablecoins settle in seconds for under a cent on fast networks USDT on Tron remains the default "African stablecoin" because of Binance's dominance as the primary exchange and Tron's low withdrawal fees. But USDC on Solana and Base is growing as direct-to-wallet usage increases and new payment infrastructure supports these networks natively. ## The Remittance Angle Sub-Saharan Africa receives $50-60 billion in annual remittances. The World Bank's 2025 data shows the region has the highest transfer costs globally: 8.78% average for a $200 transfer, compared to the 6.49% global average. A $200 remittance through traditional rails costs $17.56 in fees and takes 1-3 days. The same transfer in USDT on Tron costs under $0.10 and settles in 2 minutes. On Solana or Base, it costs under a cent and settles in seconds. That 99%+ cost reduction explains why stablecoin volumes across African corridors keep climbing. For merchants, this means a growing share of incoming customer payments originates as crypto remittances. ## What a Payment Gateway Needs for Africa Building or choosing crypto payment infrastructure for African markets requires five things: **Multi-chain support.** Not optional. Bitcoin for purchases, Tron for USDT transfers, Solana and Base for low-fee stablecoin payments, Ethereum for high-value settlement. A single-chain solution loses the majority of potential transactions. See [why single-blockchain checkout kills conversion](https://coincircuit.io/blog/multi-chain-merchant-conversion-rates/). **Local fiat settlement.** NGN in Nigeria, ZAR in South Africa, KES in Kenya. Merchants need to receive local currency. A gateway that only settles in USD or stablecoins excludes most small and medium businesses. **Sub-cent fee tolerance.** African crypto transactions skew smaller. The median payment amount is well under $1,000. A $0.50 gas fee on a $100 transaction is 0.5%, which users notice. The gateway needs to route through low-fee networks by default. **Regulatory compliance per market.** Each country has different rules. Nigeria needs SEC VASP compliance. South Africa needs FSCA registration. Kenya is evolving. Ethiopia restricts crypto for domestic payments. Compliance is country-specific, not continent-wide. **P2P bridge compatibility.** Many African crypto users hold assets on exchanges (primarily Binance) rather than in self-custody wallets. The payment flow often involves an exchange withdrawal to a payment address. The gateway needs to handle exchange-withdrawal transactions cleanly, including varying confirmation times and occasional memo/tag requirements. ## The $205 Billion Opportunity Africa's crypto economy is real, growing, and commercially active. The $205 billion in on-chain value is not just trading volume. It includes remittances, merchant payments, freelance income, and cross-border B2B settlement. CoinCircuit operates across these markets with multi-chain support (Bitcoin, Ethereum, Solana, BSC, Tron, Base, Arbitrum), local fiat settlement in NGN and other currencies, and a 1% flat fee that works for African transaction sizes. One API integration covers all five markets and all major blockchains. See the [business page](https://coincircuit.io/business/) for merchant details or the [developer docs](https://coincircuit.io/docs/) to start integrating. ### Start accepting crypto today Developer friendly API. Instant settlements. No hidden fees. [Get Started Now](https://coincircuit.io/docs/) --- # Stablecoins vs CBDCs: What the Data Says for African Fintech Builders | CoinCircuit Blog > eNaira has 13 million wallets and 270,000 active users. USDT on Tron moves billions monthly across Africa. The numbers tell the story. Source: https://coincircuit.io/blog/stablecoins-vs-cbdcs/ Markdown: https://coincircuit.io/blog/stablecoins-vs-cbdcs.md [Back to Blog](https://coincircuit.io/blog/) Global Architecture # Stablecoins vs CBDCs: What the Data Says for African Fintech Builders Chidubem Ogbuefi Mar 24, 2026 Less than 1 min read *Stablecoins vs CBDCs: What the Data Says for African Fintech Builders* ## 13 Million Wallets, 270,000 Active Users Nigeria launched the eNaira in October 2021 on Hyperledger Fabric, making it the first African retail CBDC. Four years in, adoption remains marginal. 13 million wallets created. 270,000 active users. That is under 1% of Nigeria's population. The IMF flagged inactivity rates as high as 98%. Total eNaira in circulation sits at ₦18.3 billion, roughly $11 million USD. During the 2023 cash shortage, usage spiked briefly (₦22 billion in transactions over a short period). Once cash returned, activity dropped. Only 33% of eNaira users were previously unbanked, which weakens the financial inclusion case the CBN built around it. Meanwhile, Nigeria processed $92.1 billion in on-chain crypto value in 2024-2025 (Chainalysis). Stablecoins account for 43% of Sub-Saharan African crypto activity. $92.1 billion vs $11 million. Stablecoin volume in Nigeria outpaces eNaira circulation by roughly 8,000x. ## The Rest of Africa's CBDC Landscape Nigeria is the only African country with a live retail CBDC. Everyone else is still in pilot or research: **Ghana (e-Cedi):** Completed a 2,750-person pilot in 2022 that tested offline functionality. Full retail launch targeted for late 2025/2026, delayed by economic conditions and legislative gaps. **South Africa (Project Khokha):** Wholesale-only. Focused on interbank settlement and tokenized securities on DLT infrastructure. No retail CBDC planned. **Kenya:** Research and consultation phase. The priority is interoperability with M-Pesa, which already dominates mobile payments. Roughly 11 African countries are exploring or piloting CBDCs. None have matched Nigeria's launch, and Nigeria's results are not encouraging. ## Why the Gap Exists: Technical Constraints The eNaira runs on Hyperledger Fabric, a permissioned blockchain. The Central Bank of Nigeria operates all validation nodes, controls access, and enforces transaction limits at the consensus layer. For developers, this means: **Tiered transaction limits.** Tier 0 (basic KYC): ₦20,000 daily limit. Higher tiers require progressively heavier compliance, up to ₦1 million daily with full documentation. **Restricted APIs.** Integration goes through the CBN's Digital Currency Management System. It requires regulatory approval, bank partnerships, and compliance-gated onboarding. A multi-week bureaucratic process before you write your first API call. **No smart contract programmability.** You cannot deploy custom logic on the eNaira ledger. There are no composable building blocks. Every new feature requires CBN coordination. **Limited cross-border functionality.** The eNaira is designed for domestic use. Cross-border settlement requires separate bilateral agreements that do not exist yet. Compare this to USDT on Tron or USDC on Base: standard ERC-20/TRC-20 tokens, a few lines of ethers.js, no approval process, programmable via smart contracts, and accessible to any developer on earth. ## cNGN: The Regulated Middle Ground In February 2025, WrappedCBDC Ltd (backed by the Africa Stablecoin Consortium) launched cNGN, a naira-pegged stablecoin licensed by Nigeria's SEC. It is 1:1 fiat-backed with reserves at ₦2.3 billion. Around 2,968 holders so far, with hundreds of millions of naira traded cumulatively. cNGN sits in an interesting position: blockchain-native like USDT/USDC (programmable, composable, fast), but naira-denominated and regulated under Nigerian law. For merchants who need naira settlement without the eNaira's limitations, it is the emerging option. ## The Remittance Problem Sub-Saharan Africa receives $50-60 billion in annual remittances. The World Bank's 2025 data shows the region has the highest transfer costs globally: 8.78% average for a $200 transfer, compared to the 6.49% global average. Banks are the most expensive channel. A $200 remittance through traditional rails costs $17.56 in fees and takes 1-3 days. The same transfer in USDT on Tron costs under $0.10 and settles in 2 minutes. On Base or Solana, it costs under a cent and settles in seconds. Stablecoins cut remittance costs by over 99%. That spread explains why Tron USDT volumes across African corridors keep climbing. ## The Comparison Table Dimension Stablecoins (USDC/USDT) CBDCs (eNaira) cNGN Liquidity $169B+ global (Ethereum alone) $11M circulation ₦2.3B (~$1.4M) Blockchains Ethereum, Tron, Solana, Base, BSC Hyperledger Fabric (permissioned) Multiple public blockchains Developer access Open. ethers.js + wallet. Minutes. CBN DCMS API. Weeks of approvals. Open. Standard token interface. Transaction limits None (protocol level) ₦20k-₦1M daily (tiered KYC) Cross-border Native. Any blockchain, any country. Domestic only Native on supported blockchains Programmability Full smart contract composability No custom logic Settlement speed 0.4 sec (Solana) to 36 sec (Ethereum) Seconds (when online) Depends on blockchain Peg USD NGN Regulation Varies by jurisdiction CBN-issued SEC Nigeria licensed ## What This Means for Builders If you are building payment infrastructure for African merchants, the comparison is lopsided. Stablecoins already process billions in African transaction value. CBDCs process millions. The developer experience gap is even wider: open APIs and standard token interfaces vs. weeks of regulatory onboarding for restricted functionality. cNGN adds a naira-denominated option that runs on public blockchains. For use cases that need local currency settlement with blockchain programmability, it fills a gap that neither eNaira nor dollar stablecoins cover alone. CoinCircuit supports USDT and USDC across seven blockchains today. As regulated local stablecoins like cNGN mature, the same API and settlement infrastructure extends to cover them. The integration stays the same. The asset options grow. For a practical guide to accepting crypto in Nigeria, see [Crypto Payments in Nigeria: What Merchants Should Know](https://coincircuit.io/blog/accept-crypto-payments-nigeria/). ### Start accepting crypto today Developer friendly API. Instant settlements. No hidden fees. [Get Started Now](https://coincircuit.io/docs/) --- # The Multi-Chain Merchant: Why Your Customers Are on Different Blockchains | CoinCircuit Blog > Which blockchains your customers actually use, what the data says, and why single-network checkout kills conversion. Source: https://coincircuit.io/blog/multi-chain-merchant-conversion-rates/ Markdown: https://coincircuit.io/blog/multi-chain-merchant-conversion-rates.md [Back to Blog](https://coincircuit.io/blog/) Global Architecture # The Multi-Chain Merchant: Why Your Customers Are on Different Blockchains and What to Do About It Chidubem Ogbuefi Mar 23, 2026 Less than 1 min read *The Multi-Chain Merchant: Why Your Customers Are on Different Blockchains and What to Do About It* ## A $0.50 Fee Just Lost You a Customer Your checkout page says Ethereum only. Your customer holds USDC on Solana. To pay you, they need to bridge to Ethereum: $0.50+ in gas, 10-15 minutes of waiting, and a bridge UI they may not trust. Most of them leave. This is the single-blockchain problem. You built a payment flow that works on one network, and your customers live on five. ## Where the Money Actually Lives Stablecoin volume hit $33 trillion in 2025, according to Plasma Finance. That money does not sit on one blockchain. It is spread across networks based on cost, speed, and habit. Here is where stablecoin supply concentrates today: - **Tron**: $83.9B in USDT. Over 95% of all stablecoins on Tron are USDT. - **Ethereum**: $25.3B in USDC, plus large USDT holdings. The institutional settlement layer. - **Solana**: $2.19B in USDC, growing fast. $650B monthly stablecoin transfer volume, now leading all blockchains (Binance Research). - **Base**: $2.96B in USDC. Coinbase's L2, absorbing consumer USDC flow. - **BSC**: BNB-native traffic plus bridged USDC and FDUSD. USDC recently flipped USDT in transfer volume, now accounting for over 50% of stablecoin transactions globally (ForkLog). But USDT still dominates in supply, and Tron still dominates USDT. Your customers are split across these blockchains. If you only accept one, you are filtering out the rest. ## The Fee Gap: Why Customers Pick Solana, Base, and Arbitrum Over Ethereum Ethereum mainnet processes under 1.2 million transactions per day. Base handles roughly 7 million. Solana does 70 million. L2s like Base and Arbitrum are growing faster than Ethereum L1: Base TPS grew 51% recently, Arbitrum 17.5% (Binance). Solana, an L1 built for throughput, is pulling ahead of all of them in raw transaction count. The reason is simple: fees and speed. But fees vary depending on whether you are sending a native asset (ETH, SOL, BNB) or a token (USDC, USDT). Token transfers cost more because they execute smart contract logic on top of the base transaction. Blockchain Native Transfer Token Transfer (USDC/USDT) Finality Ethereum L1 ~$0.15 ~$0.50+ ~36 sec Arbitrum ~$0.01 ~$0.03 <1 sec Base <$0.01 ~2 sec Solana <$0.001 ~$0.002 ~0.4 sec Tron ~$0.10 ~$2+ (TRC-20 contracts) ~2 min BSC ~3 sec Bitcoin $1-5+ N/A (no tokens) ~20 min Tron deserves a closer look. Its reputation as the cheap USDT network comes from exchange withdrawals, where the exchange covers the contract execution fee. Sending TRC-20 USDT from a non-custodial wallet costs around $2 in energy/bandwidth fees. Most USDT on Tron lives in exchange wallets, not personal ones. Tron retains its volume through early adoption and exchange infrastructure, not because it is the cheapest option for end users. A customer sending $50 in USDC picks Base or Solana. A customer sending $50,000 picks Ethereum for finality guarantees. A customer in Lagos with USDT on Binance withdraws via Tron because the exchange covers the fee. Each of these is a valid path. You need to accept all of them. ## Africa: $205 Billion in On-Chain Value Sub-Saharan Africa processed over $205 billion in on-chain value between 2024-2025, growing 52% year-over-year (Chainalysis). Nigeria alone accounted for $92.1 billion. The pattern here is distinct from the rest of the world: **Bitcoin dominates purchases.** 89% of crypto purchases in Nigeria involve Bitcoin. 74% in South Africa. People use BTC as a store of value against currency devaluation and for cross-border remittances. **Stablecoins dominate payments.** 43% of Sub-Saharan African crypto activity involves stablecoins (Chainalysis via RootData). When people pay for services, they pay in USDT or USDC. Tron is the default rail for USDT remittances across the continent. **Retail-sized transfers drive volume.** Most transactions are under $10,000. Fee sensitivity is high. A $0.50 gas fee on a $100 Ethereum payment is 0.5% of the transaction. On Solana or Base, that same transfer costs under a cent. If you are building payments infrastructure for African merchants, you need Bitcoin for store-of-value flows, Tron for existing exchange-based USDT liquidity, and low-fee networks like Solana, Base, and Arbitrum for the cost-sensitive majority. For a market-by-market breakdown of blockchain preferences, see [Crypto Payments Across Africa: Five Markets, Five Payment Stacks](https://coincircuit.io/blog/crypto-payments-africa/). ## The Regime Shift in Stablecoin Networks The dominant blockchain for stablecoin payments is changing. Three years ago, Tron owned 36% of stablecoin transaction share. Today it holds 14.6% (ForkLog). Solana took the lead. Base is climbing. Period Dominant Blockchain Driver 2020-2023 Cheap USDT transfers 2023-2025 Ethereum + L2s DeFi and institutional adoption 2025-2026 Payment speed and near-zero fees Tron is not dead. $83.9 billion in USDT still lives there. But the growth is elsewhere. Solana processed 8.7 billion transactions in the last 30 days (CryptoSlate), roughly 70 million per day. Ethereum L1 does under 1.2 million. For a payment processor, this means the blockchain mix of your customers is shifting under your feet. What worked 18 months ago will cost you conversions today. ## What Multi-Blockchain Support Looks Like in Practice A payer on Tron sends USDT. A payer on Base sends USDC. A payer on Bitcoin sends BTC. Your merchant sees one unified balance in USD. The payment gateway handles: - Network detection from the incoming transaction - Asset-specific confirmation thresholds (1 confirmation on Base, 6 on Bitcoin, 3 on Ethereum) - Real-time exchange rate locking at session creation - Fee calculation per blockchain - Unified settlement into the merchant's balance The merchant never configures routing rules. The payer picks the blockchain they already hold assets on. Friction drops to zero. ## The Cost of Getting This Wrong Single-blockchain checkout creates three failure modes: **Bridge abandonment.** The customer needs to move assets to your blockchain. Bridges are slow, expensive, and confusing. Many users abandon at this step. **Gas sticker shock.** A customer on Ethereum L1 paying for a $10 service sees a $0.50 gas fee (5% surcharge). On Base, the same transaction costs $0.01. **Asset mismatch.** Your checkout accepts USDC. Your customer holds USDT on Tron. Without multi-blockchain support, that customer cannot pay you at all. Each of these is a lost conversion. Multiply across hundreds of daily transactions and the revenue impact compounds fast. ## CoinCircuit's Approach CoinCircuit supports Bitcoin, Ethereum, Solana, BSC, Tron, Base, and Arbitrum. Merchants accept BTC, ETH, USDT, USDC, SOL, BNB, TRX, and DOGE across these networks through a single API integration. One `POST /api/v1/payments` call. The payer selects their blockchain and asset on the checkout page. Settlement normalizes into the merchant's fiat or stablecoin balance. No network management, no bridge configuration, no multi-wallet overhead. ### Start accepting crypto today Developer friendly API. Instant settlements. No hidden fees. [Get Started Now](https://coincircuit.io/docs/) --- # How to Sign a Gasless Stablecoin Payment | CoinCircuit Blog > Code examples for signing gasless stablecoin payments with EIP-3009 (USDC on Base, Arbitrum), Permit2 (USDC, USDT on Base, Arbitrum, BSC), and Solana partial transaction signing. Source: https://coincircuit.io/blog/how-to-sign-gasless-payment/ Markdown: https://coincircuit.io/blog/how-to-sign-gasless-payment.md [Back to Blog](https://coincircuit.io/blog/) Developer Guide # How to Sign a Gasless Stablecoin Payment Chidubem Ogbuefi Mar 21, 2026 Less than 1 min read *How to Sign a Gasless Stablecoin Payment* ## Three Schemes, One Result CoinCircuit settles gasless stablecoin payments across EVM blockchains and Solana. The sender signs a payment authorization off-chain. CoinCircuit submits it on-chain and covers gas. This guide shows how to build the signed payload for each scheme. You need ethers.js v6 for EVM chains or @solana/web3.js for Solana. ## EIP-3009: USDC on EVM Chains USDC implements `transferWithAuthorization` (EIP-3009). You sign an EIP-712 typed data message authorizing a token transfer from your wallet. Anyone can submit the signed message on-chain. The signer pays zero gas. ``` import { ethers } from 'ethers'; const provider = new ethers.JsonRpcProvider('https://mainnet.base.org'); const usdcAddress = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'; // Query the contract for EIP-712 domain fields const usdc = new ethers.Contract(usdcAddress, [ 'function name() view returns (string)', 'function version() view returns (string)', ], provider); const domain = { name: await usdc.name(), // "USD Coin" on Base mainnet version: await usdc.version(), // "2" chainId: 8453, verifyingContract: usdcAddress, }; const types = { TransferWithAuthorization: [ { name: 'from', type: 'address' }, { name: 'to', type: 'address' }, { name: 'value', type: 'uint256' }, { name: 'validAfter', type: 'uint256' }, { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' }, ], }; const wallet = new ethers.Wallet('YOUR_PRIVATE_KEY'); const message = { from: wallet.address, to: '0xDepositAddress...', value: '1000000', // 1.00 USDC validAfter: '0', validBefore: String(Math.floor(Date.now() / 1000) + 3600), nonce: ethers.hexlify(ethers.randomBytes(32)), }; const signature = await wallet.signTypedData(domain, types, message); ``` Two things to get right: The `domain` must match what the USDC contract expects. Always query `name()` and `version()` from the contract itself. Base mainnet returns "USD Coin" / "2". Base Sepolia returns "USDC" / "2". Arbitrum returns "USD Coin" / "2". A mismatched domain produces an invalid signature that reverts on-chain. The `nonce` is a random 32-byte hex value. The USDC contract tracks used nonces per sender address. Each value can only be used once. ## Permit2: USDC, USDT, and Other ERC-20 Tokens USDC, USDT, and tokens without built-in gasless support use Uniswap's Permit2. Two steps: a one-time on-chain approval, then off-chain signing for each payment. **One-time setup:** approve the Permit2 contract to spend your tokens. ``` const usdt = new ethers.Contract(usdtAddress, [ 'function approve(address spender, uint256 amount)', ], signer); await usdt.approve( '0x000000000022D473030F116dDEE9F6B43aC78BA3', // Permit2 ethers.MaxUint256, ); ``` **Per-payment signing:** ``` import { ethers } from 'ethers'; const PERMIT2 = '0x000000000022D473030F116dDEE9F6B43aC78BA3'; const usdtAddress = '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9'; // USDT on Arbitrum const domain = { name: 'Permit2', chainId: 42161, verifyingContract: PERMIT2, }; const types = { PermitTransferFrom: [ { name: 'permitted', type: 'TokenPermissions' }, { name: 'spender', type: 'address' }, { name: 'nonce', type: 'uint256' }, { name: 'deadline', type: 'uint256' }, ], TokenPermissions: [ { name: 'token', type: 'address' }, { name: 'amount', type: 'uint256' }, ], }; const wallet = new ethers.Wallet('YOUR_PRIVATE_KEY'); const deadline = String(Math.floor(Date.now() / 1000) + 3600); const nonce = String(Math.floor(Math.random() * 2 ** 48)); const message = { permitted: { token: usdtAddress, amount: '1000000' }, spender: ethers.ZeroAddress, // CoinCircuit fills this at settlement nonce: BigInt(nonce), deadline: BigInt(deadline), }; const signature = await wallet.signTypedData(domain, types, message); ``` The Permit2 contract deploys at the same address on every EVM blockchain: `0x000000000022D473030F116dDEE9F6B43aC78BA3`. The `spender` in the signed message must match whoever calls `permitTransferFrom` on-chain. CoinCircuit resolves this at settlement time. Set it to `ethers.ZeroAddress` when building payloads. ## Solana: Native Fee Payer Abstraction Solana transactions support separate fee payers at the protocol level. You build a transaction, set CoinCircuit's wallet as the fee payer, sign your part, and send the partially signed transaction. CoinCircuit adds its signature and submits. ``` import { Connection, Transaction, SystemProgram, PublicKey, Keypair, } from '@solana/web3.js'; const connection = new Connection( 'https://api.mainnet-beta.solana.com', 'confirmed', ); const sender = Keypair.fromSecretKey(yourSecretKeyBytes); const recipient = new PublicKey('RecipientAddress...'); const feePayer = new PublicKey('CoinCircuitFeePayerKey...'); const { blockhash } = await connection.getLatestBlockhash('confirmed'); const tx = new Transaction({ recentBlockhash: blockhash, feePayer }); tx.add(SystemProgram.transfer({ fromPubkey: sender.publicKey, toPubkey: recipient, lamports: 11771200, // 0.0117712 SOL })); // Partially sign with your key only tx.partialSign(sender); const transaction = tx .serialize({ requireAllSignatures: false }) .toString('base64'); ``` For SPL token transfers (USDC, USDT on Solana), replace `SystemProgram.transfer` with the SPL Token `createTransferInstruction` from `@solana/spl-token`. Solana transactions expire after roughly 60 seconds based on the blockhash. Generate the transaction close to when you plan to submit it. ## Building the Settle Payload Each scheme produces a flat payload with `from`, `to`, `value`, and scheme-specific fields. Wrap it in the settle request body. **EIP-3009 (USDC on Base):** ``` { "scheme": "eip3009", "chain": "base", "asset": "USDC", "payload": { "from": "0xYourWallet...", "to": "0xDepositAddress...", "value": "1000000", "validAfter": "0", "validBefore": "1774055094", "nonce": "0xrandom32bytes...", "signature": "0xYourSignature..." } } ``` **Permit2 (USDT on Arbitrum):** ``` { "scheme": "permit2", "chain": "arbitrum", "asset": "USDT", "payload": { "from": "0xYourWallet...", "to": "0xDepositAddress...", "value": "1000000", "deadline": "1774055094", "nonce": "42", "signature": "0xYourSignature..." } } ``` **Solana (SOL):** ``` { "scheme": "solana", "chain": "solana", "asset": "SOL", "payload": { "from": "YourSolanaPublicKey...", "to": "RecipientPublicKey...", "value": "11771200", "transaction": "base64EncodedPartiallySignedTx..." } } ``` POST this to `https://api.coincircuit.io/api/v1/payments/agent/settle` with your API key. CoinCircuit validates the payload, submits it on-chain, covers gas, and returns the transaction hash. ## Quick Reference Scheme Assets Chains Signing Standard Key Fields eip3009 USDC Base, Arbitrum EIP-712 validAfter, validBefore, nonce (32-byte hex), signature permit2 USDC, USDT Base, Arbitrum, BSC deadline, nonce (numeric), signature solana SOL, USDC, USDT Solana Partial tx signing transaction (base64) For the full resource server integration flow, see [x402: How to Accept Payments from AI Agents on Your API](https://coincircuit.io/blog/x402-machine-to-machine-payments/). ### Start accepting crypto today Developer friendly API. Instant settlements. No hidden fees. [Get Started Now](https://coincircuit.io/docs/) --- # x402: How to Accept Payments from AI Agents on Your API | CoinCircuit Blog > A developer guide to x402 gasless payments: EIP-3009, Permit2, and Solana signing schemes, resource server integration, and settlement via the CoinCircuit API. Source: https://coincircuit.io/blog/x402-machine-to-machine-payments/ Markdown: https://coincircuit.io/blog/x402-machine-to-machine-payments.md [Back to Blog](https://coincircuit.io/blog/) Machine Economy # x402: How to Accept Payments from AI Agents on Your API Chidubem Ogbuefi Mar 18, 2026 Less than 1 min read *x402: How to Accept Payments from AI Agents on Your API* ## x402: The Payment Protocol That Took 35 Years The original 1991 HTTP spec reserved status code 402 for digital payments. Credit cards need minimum transaction floors. SWIFT needs human sign-off at every hop. Neither works when a machine needs to pay $0.002 for an API call and retry in milliseconds. x402 builds on that status code. It pairs the 402 response with gasless stablecoin transfers, letting AI agents pay for resources programmatically. Three signing schemes cover the major chains and assets: EIP-3009 for USDC on Base and Arbitrum, Permit2 for USDC and USDT on all EVM chains, and native fee payer abstraction for Solana. ## Key Concepts **EIP-3009 (TransferWithAuthorization):** A standard built into USDC that lets a wallet holder sign a transfer off-chain. The signed authorization can be submitted by anyone. The signer never pays gas. Supported on Base and Arbitrum only. **Permit2:** Uniswap's universal approval contract. Works with any ERC-20 token, including USDC, USDT, and tokens without built-in gasless transfer support. The token holder approves the Permit2 contract once on-chain, then signs individual transfer permits off-chain for each payment. CoinCircuit submits the permit and covers gas. Supported on Base, Arbitrum, and BSC. **Solana fee payer abstraction:** Solana transactions natively support separate fee payers. The agent builds a transfer, designates CoinCircuit's wallet as the fee payer, and partially signs. CoinCircuit adds its fee payer signature and submits. Works with SOL, USDC, and USDT on Solana. **Gasless payment:** The agent signs an authorization to move tokens from their wallet to a deposit address. The resource server (your backend) submits this signed payload to CoinCircuit, which settles it on-chain and covers gas. The agent only needs a wallet and a signing key. **Resource server:** Your API backend. You create the payment session, return the 402 response to the agent, receive the signed payload back, and call CoinCircuit to settle it. ## How the x402 Flow Works Your server creates a payment session. The agent signs a payment authorization using the appropriate scheme for their blockchain and asset. Your server submits the signed payload to CoinCircuit for on-chain settlement. For a step-by-step guide on building signed payloads for each scheme, see [How to Sign a Gasless Stablecoin Payment](https://coincircuit.io/blog/how-to-sign-gasless-payment/). ### Step-by-Step **1\. Agent requests your resource** The agent sends a request to your API: ``` GET /api/premium-data ``` **2\. Your server creates a payment session** Your backend calls CoinCircuit to create a checkout session: ``` POST https://api.coincircuit.io/api/v1/payments x-api-key: sk_live_your_key { "amount": "1.00", "currency": "USD", "asset": "USDC", "chain": "base", "customer": { "email": "agent@example.com" } } ``` The response includes a deposit address, the required USDC amount, and a session reference. **3\. Your server responds with 402** Return the payment details to the agent: ``` HTTP/1.1 402 Payment Required { "paymentRequired": { "chain": "base", "asset": "USDC", "amount": "1000000", "depositAddress": "0xabc...def" } } ``` Your server keeps the session reference internally for settlement. **4\. Agent signs the payment** The agent signs a gasless payment authorization using the scheme that matches its blockchain and asset. Every scheme produces a flat payload with `from`, `to`, `value`, and scheme-specific fields. The agent sends the signed payload back to your server: ``` POST /api/premium-data/pay { "scheme": "eip3009", "payload": { "from": "0xAgentWallet...", "to": "0xabc...def", "value": "1000000", "validAfter": "0", "validBefore": "1774055094", "nonce": "0xrandom32bytes...", "signature": "0xabcd...1234" } } ``` **5\. Your server settles via CoinCircuit** Your backend submits the signed payload to CoinCircuit for on-chain settlement: ``` POST https://api.coincircuit.io/api/v1/payments/agent/settle x-api-key: sk_live_your_key { "sessionReference": "cs_ref_abc123", "scheme": "eip3009", "chain": "base", "asset": "USDC", "payload": { "from": "0xAgentWallet...", "to": "0xabc...def", "value": "1000000", "validAfter": "0", "validBefore": "1774055094", "nonce": "0xrandom32bytes...", "signature": "0xabcd...1234" } } ``` CoinCircuit validates the session requirements, submits the transaction on-chain, and covers gas. The response includes the transaction hash and block confirmation. **6\. Your server releases the resource** Once you receive a successful settlement response, deliver the resource to the agent. ### Integration Flow ``` Agent -> GET /api/premium-data Server -> CoinCircuit: POST /payments (creates session) Server -> Agent: 402 (deposit address, amount) Agent -> Signs payment (eip3009 / permit2 / solana) Agent -> Server: POST /pay (signed payload) Server -> CoinCircuit: POST /payments/agent/settle Server -> Agent: 200 (resource delivered) ``` ## Pre-Validating Payments Before settling, you can dry-run the payment to catch problems early. Call the verify endpoint with the same payload: ``` POST https://api.coincircuit.io/api/v1/payments/agent/verify x-api-key: sk_live_your_key ``` This runs scheme-specific checks without touching the blockchain. For EIP-3009: authorization timestamps, nonce replay, and sender balance. For Permit2: deadline and sender balance. Returns 200 if the payment will succeed, or 400 with per-check pass/fail results. ## Supported Chains and Assets Scheme Asset Chains eip3009 USDC Base, Arbitrum permit2 USDC, USDT Base, Arbitrum, BSC solana SOL, USDC, USDT Solana All EVM networks offer sub-second block times and gas costs under a cent. Solana settles in under a second with fees below $0.001. ## Why the Resource Server Submits The agent signs the authorization, but your server submits it. Two reasons: You control the session lifecycle. By submitting through your backend, you tie the settlement to your checkout session, validate the amount, and confirm payment before releasing the resource. The agent stays simple. The agent only needs a wallet and signing capability. No CoinCircuit API key, no gas tokens, no blockchain node. Sign and hand off. ### Start accepting crypto today Developer friendly API. Instant settlements. No hidden fees. [Get Started Now](https://coincircuit.io/docs/) --- # The Agentic Web: Why AI Assistants Need Crypto Rails to Function | CoinCircuit Blog > AI agents spend real money on APIs, compute, and data, but traditional payment rails block them at every step. Stablecoin infrastructure fills the gap. Source: https://coincircuit.io/blog/ai-assistants-crypto-rails/ Markdown: https://coincircuit.io/blog/ai-assistants-crypto-rails.md [Back to Blog](https://coincircuit.io/blog/) Machine Economy # The Agentic Web: Why AI Assistants Need Crypto Rails to Function Chidubem Ogbuefi Mar 16, 2026 Less than 1 min read *The Agentic Web: Why AI Assistants Need Crypto Rails to Function* ## An Agent With a Budget and No Way to Spend It AI agents are closing sales deals, writing and deploying code, and consuming millions of dollars in API credits every month. 62% of organizations are experimenting with them. 23% are scaling them in production (McKinsey). These agents do real work, and real work costs real money. Every LLM call runs $0.0015 to $0.10. An agent orchestration step with 5-10 tool calls can hit $0.50 or more. GPU compute for inference runs $0.50 to $10 per hour. A moderately active enterprise agent burns $500 to $2,500 per month in API and compute costs alone. When an agent needs to pay for an API call, buy cloud credits, or access a premium dataset, it hits a wall. Stripe requires human KYC. Bank APIs demand 2FA. ACH takes 1-3 days. Card networks impose 30-cent minimum fees and flag high-frequency automated transactions as fraud. These rails were built for humans typing card numbers into forms, not machines that pay $0.002 for a data lookup and retry in milliseconds. ## The Scale of the Agent Economy The AI agent market reached $7.84 billion in 2025 (MarketsandMarkets). Projections put it at $52.62 billion by 2030, a 46.3% CAGR. BCC Research tracks a similar curve: $8 billion to $48.3 billion over the same period. Gartner predicts AI agents will intermediate over $15 trillion in B2B purchases by 2028, with 90% of B2B buying decisions handled by agents and 25% of IT work done by AI alone by 2030. All of these agents need to transact, and the payment infrastructure they depend on was designed for humans filling out forms. ## Why Traditional Rails Break Four failure modes block agents from spending money: **Identity requirements.** Stripe, PayPal, and every regulated payment processor require human identity verification. An agent cannot open a bank account, pass KYC, or hold a credit card. There is no "Know Your Agent" framework in traditional finance. **Human-in-the-loop authentication.** Bank APIs require 2FA, CAPTCHA challenges, and manual approval steps. These exist to stop bots. Agents are bots. The security model treats them as threats, not customers. **Settlement latency.** ACH takes 1-3 days. Wire transfers take hours. An agent running a loop that calls a paid API, processes the response, and calls again needs settlement in seconds. Multi-day clearing kills the loop. **Fee floors and fraud rules.** Card networks charge a minimum of ~30 cents per transaction. An agent making 10,000 API calls at $0.01 each cannot pay $0.30 per call. High-frequency automated patterns also trigger fraud detection, blocking the card entirely. ## MCP: How Agents Connect to Tools The Model Context Protocol started at Anthropic and now lives under the Linux Foundation's Agentic AI Foundation. It is the standard for connecting language models to external tools and services. Over 10,000 active public MCP servers exist today. 97 million monthly SDK downloads, up 970x in 12 months. 300+ MCP clients deployed. OpenAI, Anthropic, Google, Microsoft, Cursor, VS Code, and every major cloud provider supports it. MCP gives agents a standardized way to discover services, authenticate, and execute actions. An agent with MCP access can find a payment API, read its capabilities, and call it through the same protocol it uses to read files or query databases. MCP solves the connection problem. The agent still needs a payment rail that works without human identity, settles in seconds, and handles sub-cent transactions. ## Crypto as the Agent Payment Layer Stablecoins processed $33 trillion in 2025, growing 72% year-over-year. USDC and USDT dominate cross-border and API-driven flows, settling in seconds on networks like Base and Solana for under a cent per transaction. The x402 protocol (built on the HTTP 402 status code) pairs stablecoin payments with the existing web request model. An agent hits a paid API, gets a 402 response with payment details, signs a stablecoin transfer, and the resource server settles it on-chain. No KYC. No 2FA. No minimum fees. Settlement in under 2 seconds on networks like Base and Solana. x402 launched in May 2025. By March 2026, it reached $600 million annualized volume with over 119 million transactions on Base alone. Google, Stripe, Visa, Mastercard, AWS, and Cloudflare all back it. The stack looks like this: ``` Agent discovers service (MCP) ↓ Agent authenticates (MCP key / API key) ↓ Agent receives payment request (HTTP 402) ↓ Agent signs stablecoin authorization (EIP-3009) ↓ Resource server settles on-chain (x402) ↓ Resource delivered (<2 sec) ``` The agent holds stablecoins in a wallet, signs transfers with its private key, and pays for what it uses. No bank account, no credit card, no human approval required. ## What This Means for Developers If you run an API, a SaaS product, or any service that agents consume, you have a new customer segment that cannot pay you through Stripe. They can pay you through crypto. CoinCircuit's MCP server exposes payment tools directly to agents. An agent connected to CoinCircuit can create payment sessions, check balances, and settle transactions through the same MCP interface it uses for everything else. For resource servers, the integration is a single API call. Create a checkout session, return the payment details to the agent, receive the signed authorization, and settle through CoinCircuit. The agent pays in USDC. You receive fiat or stablecoin settlement. No wallet management, no node infrastructure, no gas fee complexity. The agent economy is growing at 46% per year, and these agents are already spending money. If your infrastructure cannot accept it, someone else's will. ### Start accepting crypto today Developer friendly API. Instant settlements. No hidden fees. [Get Started Now](https://coincircuit.io/docs/)