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.

Crypto Payout Recipient

POST /api/v1/crypto-addresses: Create crypto payout recipient
Add a new crypto payout recipient by saving a wallet address you can send crypto payouts to. This is idempotent: if the same address already exists for this blockchain, the existing recipient is returned instead of an error.
GET /api/v1/crypto-addresses: List crypto payout recipients
Returns all your saved crypto payout recipients.
GET /api/v1/crypto-addresses/validate: Validate address format
Validates address format for a blockchain.
GET /api/v1/crypto-addresses/{id}: Retrieve crypto payout recipient
Returns the crypto payout recipient for the given ID.
PATCH /api/v1/crypto-addresses/{id}: Update crypto payout recipient
Updates crypto payout recipient details.
DELETE /api/v1/crypto-addresses/{id}: Delete crypto payout recipient
Deletes the crypto payout recipient.

Fiat Payout Recipient

POST /api/v1/bank-accounts: Create bank payout recipient
Adds a new bank payout recipient for receiving fiat payouts. The account will be verified and must match your name or business name.
GET /api/v1/bank-accounts: List bank payout recipients
Returns all your saved bank payout recipients.
GET /api/v1/bank-accounts/{id}: Retrieve bank payout recipient
Returns the bank payout recipient for the given ID.
PATCH /api/v1/bank-accounts/{id}: Update bank payout recipient
Updates bank payout recipient details.
DELETE /api/v1/bank-accounts/{id}: Delete bank payout recipient
Deletes the bank payout recipient. Cannot delete the only remaining recipient.
GET /api/v1/bank-accounts/banks: Retrieve bank list
Returns the list of available banks.

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/estimate: Estimate swap amount
POST /api/v1/swap/quotation: Create a swap quotation
Creates a swap quotation that locks the rate for 15 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

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.
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 and crypto payout fees across every supported payout chain and asset.

Rates

GET /api/v1/rates/convert: Retrieve conversion rate
Returns the current conversion rate between any two supported currencies. Both "from" and "to" must be provided in uppercase.
GET /api/v1/rates: Retrieve all conversion rates
Returns all available conversion rates.

Deposits

POST /api/v1/deposits/accounts: Create a deposit account
Creates a deposit account. Omit customerId to create a parent account.
GET /api/v1/deposits/accounts: List deposit accounts
Lists your deposit accounts.
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/accounts/{id}: Retrieve a deposit account
Retrieves a deposit account and its identities.
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/stats: x402 transaction stats
Payment counts and settled volume for your account over the selected period, with a time series and prior-period growth.
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.
POST /api/v1/payments/agent/settle: Settle x402 payment
Deprecated. Use POST /api/v1/x402/settle. This session-bound endpoint is superseded by the x402 facilitator. Settles a gasless x402 payment on-chain. The sender signs a payment authorization off-chain, and CoinCircuit submits the transaction and covers gas. Three schemes are supported: - **eip3009** (USDC on Base and Arbitrum): sender signs an EIP-3009 TransferWithAuthorization - **permit2** (USDC, USDT on Base, Arbitrum, BSC): sender signs a Uniswap Permit2 permit - **solana** (SOL, USDC, USDT on Solana): sender partially signs a Solana transaction, CoinCircuit co-signs as fee payer Supported on Base, Arbitrum, BSC, and Solana. Include a `sessionReference` to validate the payment against a checkout session.
POST /api/v1/payments/agent/verify: Verify x402 payment
Deprecated. Use POST /api/v1/x402/verify. This session-bound endpoint is superseded by the x402 facilitator. Dry-runs the x402 payment checks without settling on-chain. Validates scheme, chain, asset, session constraints (if sessionReference provided), and runs scheme-specific checks: - **eip3009**: timestamp validity, nonce replay, sender balance - **permit2**: deadline, sender balance - **solana**: transaction structure validation Returns 200 with `valid: true` on success, or 400 with per-check pass/fail breakdown.

Payout Recipients

POST /api/v1/recipients: Create payout recipient
Adds a payout recipient. Set type to crypto_address or ngn_bank_account 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.
GET /api/v1/recipients/banks: List supported banks
Returns the banks available for ngn_bank_account recipients.
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.
PATCH /api/v1/recipients/{id}: Update payout recipient
Updates the label or default flag. The destination is immutable: to change it, delete and recreate the recipient.
DELETE /api/v1/recipients/{id}: Delete payout recipient
Deletes the payout recipient.

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