# API Reference | CoinCircuit

> Complete API reference for CoinCircuit: endpoints, request/response schemas, authentication, webhooks, refunds, and settlements. Build with confidence.

Source: https://coincircuit.io/api-reference/

# 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