CoinCircuit API Reference

CoinCircuit REST API, full endpoint reference.

Blockchain

GET /api/v1/blockchain/assets: Retrieve detailed 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 Addresses

POST /api/v1/crypto-addresses: Create crypto address
Create new crypto payout address.
GET /api/v1/crypto-addresses: List crypto addresses
Returns all crypto addresses.
GET /api/v1/crypto-addresses/validate: Validate address format
Validates address format for a blockchain.
GET /api/v1/crypto-addresses/{id}: Retrieve crypto address
Returns the crypto address for the given ID.
PATCH /api/v1/crypto-addresses/{id}: Update crypto address
Updates crypto address details.
DELETE /api/v1/crypto-addresses/{id}: Delete crypto address
Deletes the crypto address.

Balance

GET /api/v1/balance: Retrieve balance
Returns the balance for the specified currency, or default currency if not specified.

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 for a session or invoice
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.

Transactions

GET /api/v1/transactions: List transactions
Returns all Blockchain transactions.
GET /api/v1/transactions/{txHash}: Retrieve transaction
Returns the transaction for the given hash.

Payments

POST /api/v1/payments: Create payment session
Creates a new payment session (payment link) to receive payments. If asset, chain, and customer are all provided, a deposit address is generated immediately.
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 using the specified asset and blockchain. If the session was created without customer details, the customer field is required (email, and optionally firstName, lastName, phone). If the session already has a customer attached, 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.

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.

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.

Bank Accounts

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

Invoices

POST /api/v1/invoices: Create invoice
Creates a new invoice. If no expiration date is provided, expires 12 hours after creation. Maximum expiration cannot exceed 2 days from creation. Invoices can be locked to a specific asset and chain or left open for customer selection, and support billing periods for recurring services.
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.

Settlements

GET /api/v1/settlements: List settlements
GET /api/v1/settlements/{reference}: Retrieve settlement data