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 for a guided walkthrough.
Need help? Use the AI assistant in the bottom-right corner for guidance while navigating the documentation.
Use sandbox to test your integration safely before going live.
Use sandbox API keys (test keys) against the sandbox base URL, and live keys against production.
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:
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.).
Install the CoinCircuit SDK for your language.
Node.js / TypeScript
Checkout SDK
npm | PyPI | Checkout SDK
Authenticate requests by including your API key in the x-api-key header.
CoinCircuit sends webhook events as payments progress. See the Webhooks tab in this page for detailed integration guidance.
The API uses standard HTTP status codes to indicate the success or failure of a request.
Basic Error Example:
The API is rate-limited to 20 requests per second. Exceeding this limit will result in a 429 Too Many Requests response.
List endpoints support pagination using page (default 1) and size (default 10, max 100) query parameters.
Response Metadata Example:
Production Server
Create and manage invoices
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.
Every delivery carries these headers.
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.
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.
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.
CoinCircuit is crypto payment infrastructure. Accept payments online, in person, and from AI agents. Bill with invoices, send payouts, and issue refunds.
Follow the Quick Start to take your first payment in a few minutes. To test without real funds first, set up the Sandbox.
API changes, new features, migration guides, and deprecation notices, newest first.
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.
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.
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 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.
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.
Override your dashboard webhook URL for a single object by passing a webhookUrl when you create it.
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.
A per-request webhook URL applies to payout, refund, swap, and invoice events, and to the payment events of a checkout session. An invoice's webhook URL also covers the payment session it creates, so every event for that invoice lands on one endpoint. Your dashboard webhook toggle still governs whether anything is sent.
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.
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.
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.
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.
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.
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.
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.
Fetch a single account with its identities, the parent account, or a customer's account, and list all accounts filtered by status.
A ledger feed of every entry that moved your balance, with rich source linkage and per-entry before/after balances.
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.
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.
deposit webhooks notify you when a deposit is recorded, credited, or fails, and swap.completed / swap.failed webhooks notify you when a swap finishes.
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.
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.
Deposits are listed and fetched 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.
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.
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.
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.
Execute a previously created quotation. Debits the source currency and credits the target currency atomically at the locked rate. Returns the completed swap details.
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.
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.
New endpoints for AI agent payments via the x402 protocol, plus Base and Arbitrum added as supported blockchains for all payment sessions.
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.
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.
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.
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.
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.
Base (Coinbase L2) and Arbitrum are now fully supported for all payment sessions, settlements, and agent payments.
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 One is now available for all payment sessions. Supports USDC and USDT via both EIP-3009 and Permit2 signing schemes with sub-second finality.
Major updates to the Payment API and Payouts system, introducing new payload shapes, unified endpoints, and better error handling.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Follow these steps to transition to the new format. Each step is independent — you can adopt them incrementally.
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.
Replace all session.* event type strings with the corresponding payment.* equivalents in your webhook 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.
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.
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.
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.
The response replaces the nested amount object and separate bankAccount/crypto objects with flat fields and a unified recipient object.
Open SearchKeyboard Shortcut:CTRL k Ask AI
Keyboard Shortcut:CTRL k
Keyboard Shortcut:
HTTP Method: POST
HTTP Method: GET
Retrieve invoice by reference
Payout Recipients
Powered by Scalar
Download OpenAPI Document
"https://mcp.coincircuit.io"
"2026-01-23T23:33:55.685Z"
"/api/v1/payments"
Server:https://api.coincircuit.io
https://api.coincircuit.io
Select Auth Type
No authentication selected
Client Libraries
More Select from all clients
Select from all clients
Invoices Operations
/api/v1/invoices
HeaderDescriptionX-CoinCircuit-EventThe event type, e.g. transaction.confirmedX-CoinCircuit-Delivery-IdUnique id for this deliveryX-CoinCircuit-SignatureHMAC-SHA256 signature of the payloadX-CoinCircuit-TimestampUnix timestamp of the delivery
GuidesIntroduction
NewPOST /payouts/cross-border/quote
POST /payouts/cross-border/quote
"sourceCurrency"
"cbq_123e4567-e89b-12d3-a456-426614174000"
"2026-07-22T12:02:00.000Z"
NewPay recipients in their local currency
"7c9e6679-7425-40de-944b-e07fc1f90ae7"
NewMobile money recipients
POST /recipients
"kes_mobile_money"
"institutionCode"
NewSet a webhook URL per request
"https://your-api.com/webhooks/payouts"
// Payout webhooks for this payout are delivered to webhookUrl
NewHonored across payout, refund, swap, invoice and payment events
// A per-request webhookUrl overrides your dashboard URL for:
DeprecatedIndividual recipient endpoints deprecated
// Deprecated: one endpoint per recipient type
POST /bank-accounts
POST /crypto-addresses
// Unified: one endpoint, the type field selects the shape POST /recipients
// Unified: one endpoint, the type field selects the shape
NewOne endpoint for every recipient type
// Crypto address
"crypto_address"
"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"
// NGN bank account
"ngn_bank_account"
NewIssue a deposit account per customer
POST /deposits/accounts
"123e4567-e89b-12d3-a456-426614174000"
// Omit "customerId" to create the parent (own-balance) account
NewIssue a pay-in identity into an account
// static crypto deposit address
POST /deposits/accounts/
"static_deposit_address"
// NGN virtual account
"ngn_virtual_account"
NewRetrieve and list deposit accounts
GET /deposits/accounts/
GET /deposits/accounts/by-customer/
GET /deposits/accounts?status=active&page=
NewGET /balance/transactions
GET /balance/transactions?source=payment_session¤cy=USDT
"Balance transactions retrieved successfully"
"bt_123456789_abcdef"
"payment_session"
"sourceReference"
"CC-1G3fDjgD93md"
"2026-06-01T10:30:00.000Z"
NewHow to locate the source of an entry
// session / invoice / payout entry
// swap entry (no reference)
// deposit entry (sourceId resolves at GET /deposits/:id)
"dep_123456789_abcdef"
Newdeposit.processing, deposit.completed and deposit.failed
"deposit.completed"
"depositAccountId"
"da_123456789_abcdef"
"customer@example.com"
"staticDepositAddress"
"2026-01-10T08:00:00.000Z"
"John Doe-RSRVD"
"ngnVirtualAccount"
"accountReference"
"CCVBA-7f3a9c12"
"2026-06-01T10:35:00.000Z"
Newswap.completed and swap.failed webhooks
"swap.completed"
"f2908051-6326-4708-bc73-1153209e7689"
"2026-05-29T20:25:23.680Z"
"2026-05-29T20:25:23.640Z"
"99f41fc8-47e2-4f34-a1dd-64f52ee4ff0c"
"2026-05-29T20:25:38.553Z"
"2026-05-29T20:25:23.556Z"
NewList and fetch deposits at /deposits
NewPOST /swap/quotation
POST /swap/quotation
"quotation-uuid"
"2026-05-12T10:00:15.000Z"
"2026-05-12T10:00:00.000Z"
NewPOST /swap/execute/:quotationId
POST /swap/execute/quotation-uuid
"2026-05-12T10:00:05.000Z"
NewGET /swap/estimate
GET /swap/estimate?fromCurrency=USDT&toCurrency=NGN&amount=
NewGET /swap/quotation/:quotationId
GET /swap/quotation/quotation-uuid
NewPOST /x402/requirements
POST /api/v1/x402/requirements
"https://your-api.com/api/premium-data"
// Response (return this with a 402 status)
"maxAmountRequired"
"0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b"
"maxTimeoutSeconds"
"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
NewPOST /x402/settle
POST /api/v1/x402/settle
"paymentPayload"
"0xb91c5d2e8a4f0c7d3e6b9a1f2c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d"
"0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b"
"0x9b2c4d6e8f0a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e0f2a4b6c8d0e1f3a5b7c"
"paymentRequirements"
"a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7"
"0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3"
"https://basescan.org/tx/0x4b7a1f0c9d2e5a6f8b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3"
"2026-06-25T21:09:02.000Z"
NewPOST /x402/verify
POST /api/v1/x402/verify
// Same body as settle: x402Version, paymentPayload, paymentRequirements
NewEnd-to-end x402 flow
Agent -> GET your protected resource
NewBase blockchain support
NewArbitrum blockchain support
UpdatedWebhook event types renamed: session.* → payment.*
// Previous event types "session.completed" "session.expired" "session.partial" "session.failed"
// 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 event types
"payment.completed"
"payment.expired"
"payment.partial"
"payment.underpaid"
"payment.failed"
NewNew API keys use the updated format automatically
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
NewRedesigned session response shape
// New session response
"550e8400-e29b-41d4-a716-446655440000"
"cs_ref_abc123xyz789"
"amountReceived"
"conversionRate"
Newstate replaces status
// "pending" | "completed" | "expired" | "failed"
// "open" | "closed"
// payment outcome lives in payment.status
Newsettlements included in payment API response
UpdatedPayout API deprecated — migrate to /payouts by March 30
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 /payout/fiat
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 — specify method in body
GET /payouts/fees
// unified fee lookup
NewUnified payout endpoint
// New unified request body
// "fiat" | "crypto"
// amount recipient receives
"CLIENT-REF-123"
// optional idempotency key
UpdatedAmount is what the recipient receives
// Old: amount = total deducted (fee included)
// recipient gets: 10000.00
// New: amount = what recipient gets (fee is separate)
// total deducted: 10050.00
NewRedesigned payout response
// New payout response (USDT balance → USDC payout)
"convertedAmount"
// Replace each event type:
// payment.partial → session still open, more payments expected
// data.session.state === "open"
notifyCustomerOfPartialPayment
// payment.underpaid → session closed, insufficient total received
// data.session.state === "closed"
initiateRefundFlow
// Previous — nested amount object
// New — flat amount + settlements object
// "10000.00" (plain string)
// "NGN" (plain string)
// Old — separate endpoints
// New — unified endpoint
// was balanceCurrency
// was bankAccountId or addressId
// optional idempotency key (new)
// Old — amount includes fee, recipient gets less
// you had to add fee
// recipient gets 10000.00, fee was 50.00
// New — amount IS what recipient gets
// recipient gets 10000.00, fee (50.00) charged separately
// total deducted from balance: 10050.00
// Old response fields
// nested object
// New response fields
// plain string (what recipient gets)
// plain string (amount + fee)
// "crypto_address" | "ngn_bank_account"
// cross-currency (e.g. USDT→USDC) or null
HTTP Status
Description
400
Invalid input or malformed request
401
Invalid or missing authentication
404
Resource not found
409
Resource conflict
503
Service unavailable
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
https://sandbox-api.coincircuit.iohttps://mcp.coincircuit.io{
"mcpServers": {
"coincircuit": {
"url": "https://mcp.coincircuit.io",
"headers": {
"x-mcp-key": "YOUR_MCP_KEY"
}
}
}
}npm install coincircuitpip install coincircuitnpm install @coincircuit/checkoutx-api-key: your_api_key_here{
"success": false,
"timestamp": "2026-01-23T23:33:55.685Z",
"path": "/api/v1/payments",
"method": "POST",
"error": "Unauthorized",
"message": "Unauthorized"
}429 Too Many Requests"meta": {
"page": 1,
"size": 10,
"total": 42,
"totalPages": 5
}transaction.confirmedPOST /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"
}POST /payouts
{
"currency": "KES",
"sourceCurrency": "USDT",
"amount": "10000.00",
"recipientId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"quoteId": "cbq_123e4567-e89b-12d3-a456-426614174000"
}POST /recipients
{
"type": "kes_mobile_money",
"label": "Field agent",
"details": {
"phoneNumber": "254712345678",
"accountName": "Jane Wanjiku",
"institutionCode": "MPESA"
}
}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// 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)// Deprecated: one endpoint per recipient type
POST /bank-accounts { accountName, accountNumber, bankCode }
POST /crypto-addresses { chain, address, label }// 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" }
}POST /deposits/accounts
{ "customerId": "123e4567-e89b-12d3-a456-426614174000" }
// Omit "customerId" to create the parent (own-balance) account// 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" }GET /deposits/accounts/:id
GET /deposits/accounts/parent
GET /deposits/accounts/by-customer/:customerId
GET /deposits/accounts?status=active&page=1&size=20GET /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": "...",
"bala// 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 }{
"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": "ethereu{
"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",
GET /deposits
GET /deposits/:idPOST /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/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",
"createdAGET /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/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"
}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": "0x83POST /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",
"noPOST /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"
}
}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// 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// 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// Previous
{ "status": "completed" } // "pending" | "completed" | "expired" | "failed"
// New
{ "state": "closed" } // "open" | "closed"
// payment outcome lives in payment.status{
"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" }
}
}// 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
}// 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// 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",// Replace each event type:
"session.completed" → "payment.completed"
"session.expired" → "payment.expired"
"session.partial" → "payment.partial"
"session.failed" → "payment.failed"// 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);
}// 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 // // 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)
}// 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// 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.rec