CoinCircuit API Reference

CoinCircuit REST API, full endpoint reference.

Blockchain

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.

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 receipient .
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 both fiat and crypto payout fees for a specific currency in a clean, flat structure.

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.

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
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
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.

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.

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