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/cross-border/quote: Quote a cross-border payout
Returns the fee and conversion for a cross-border payout, priced by the amount to pay from a balance (sourceAmount). Call this before creating the payout to show the cost. 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.
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