# Circle Docs: API reference

> Developer documentation for Circle's developer tools

> ## Agent Instructions
> Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}.
> Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts.
> Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md.
> Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md.
> Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers.
> Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews.
> Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming.
> Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md.
> Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors.
> API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product.
> Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes.
> When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records.
> Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md.

## API reference

- [API reference / Wallets (98 pages)](https://developers.circle.com/_llms/api-reference/wallets.txt): Documentation for API reference / Wallets.
- [API reference / Digital Asset Accounts (79 pages)](https://developers.circle.com/_llms/api-reference/digital-asset-accounts.txt): Documentation for API reference / Digital Asset Accounts.
- [API reference / Mint (137 pages)](https://developers.circle.com/_llms/api-reference/mint.txt): Documentation for API reference / Mint.
- [API reference / Circle Payments Network (103 pages)](https://developers.circle.com/_llms/api-reference/circle-payments-network.txt): Documentation for API reference / Circle Payments Network.

### Home

- [API reference](https://developers.circle.com/api-reference.md): Overview of Circle's available APIs and endpoints.
- [API keys](https://developers.circle.com/api-reference/keys.md): Learn about the different types of API keys used to authenticate requests to Circle's platform.
- [Idempotent requests](https://developers.circle.com/api-reference/idempotent-requests.md): Idempotency keys let you safely retry Circle API calls.
- [API errors](https://developers.circle.com/api-reference/errors.md): Common error response formats and codes returned by Circle APIs.
- [OpenAPI Specifications](https://developers.circle.com/api-reference/openapi-specifications.md): Find the machine-readable OpenAPI specification for every Circle API, with direct links to each published spec file.

#### Webhooks

- [Webhooks](https://developers.circle.com/api-reference/webhooks.md): Learn how Circle uses webhooks to notify your application when events occur, including the event model, delivery behavior, ordering, and idempotency.
- [How-to: Set up a webhook endpoint](https://developers.circle.com/api-reference/webhook-endpoints.md): Expose a subscriber endpoint and subscribe to webhook notifications from a Circle product.
- [How-to: Verify webhook signatures](https://developers.circle.com/api-reference/verify-webhook-signatures.md): Confirm that a webhook notification was sent by Circle by verifying its digital signature.

#### Audit Logs

- [List audit logs](https://developers.circle.com/api-reference/audit-logs/list-audit-logs.md): Returns a paginated list of audit log entries for your account, ordered from newest to oldest. Use the query parameters to filter by time range, event type, actor, or outcome. Results are paginated using opaque cursors returned in the `Link` response header.
- [Get an audit log by ID](https://developers.circle.com/api-reference/audit-logs/get-audit-log-by-id.md): Returns a single audit log entry by its unique identifier.

### Contracts

- [Contracts API](https://developers.circle.com/api-reference/contracts.md): Deploy and interact with smart contracts using Circle's managed infrastructure, including event monitoring and contract templates.
- [Postman collection](https://developers.circle.com/api-reference/contracts/postman.md): Use Circle's Postman collection to send API requests and explore the Smart Contract Platform APIs.
- [Contracts API error codes](https://developers.circle.com/api-reference/contracts/error-codes.md): Descriptions of error codes returned by the Contracts API.

#### API overview

##### Health

- [Ping](https://developers.circle.com/api-reference/contracts/common/ping.md): Checks that the service is running.

##### Webhook Subscriptions

- [Get all notification subscriptions](https://developers.circle.com/api-reference/contracts/common/get-subscriptions.md): Retrieve an array of existing notification subscriptions.
- [Create a notification subscription](https://developers.circle.com/api-reference/contracts/common/create-subscription.md): Create a notification subscription by configuring an endpoint to receive notifications. For details, see the [Notification Flows](https://developers.circle.com/wallets/webhook-notification-flows) guide.
- [Retrieve a notification subscription](https://developers.circle.com/api-reference/contracts/common/get-subscription.md): Retrieve an existing notification subscription.
- [Update a notification subscription](https://developers.circle.com/api-reference/contracts/common/update-subscription.md): Update subscription endpoint to receive notifications.
- [Delete a notification subscription](https://developers.circle.com/api-reference/contracts/common/delete-subscription.md): Delete an existing subscription.
- [Get a notification signature public key](https://developers.circle.com/api-reference/contracts/common/get-notification-signature.md): Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

##### Webhooks

- [Inbound transaction notification](https://developers.circle.com/api-reference/contracts/common/transactions-inbound.md): Sent when an inbound transaction changes state. The lifecycle state of the transaction is conveyed by the `state` field on the `notification` object.
- [Outbound transaction notification](https://developers.circle.com/api-reference/contracts/common/transactions-outbound.md): Sent when an outbound transaction changes state. The lifecycle state of the transaction is conveyed by the `state` field on the `notification` object.
- [Challenge notification](https://developers.circle.com/api-reference/contracts/common/challenges-initialize.md): Sent when a user-controlled wallet challenge changes state. The lifecycle state of the challenge is conveyed by the `state` field on the `notification` object.

#### Contracts

##### Templates

- [Estimate fee for a contract template deployment](https://developers.circle.com/api-reference/contracts/smart-contract-platform/estimate-contract-template-deploy.md): Estimate the fee required to deploy contract by template.
- [Deploy a contract from a template](https://developers.circle.com/api-reference/contracts/smart-contract-platform/deploy-contract-template.md): Deploy a smart contract using a template.

##### Interact

- [Execute a query function on a contract](https://developers.circle.com/api-reference/contracts/smart-contract-platform/query-contract.md): Query the state of a contract by providing the address and blockchain.

##### View / Update

- [List contracts](https://developers.circle.com/api-reference/contracts/smart-contract-platform/list-contracts.md): Fetch a list of contracts that you've imported and/or deployed.
- [Get a contract](https://developers.circle.com/api-reference/contracts/smart-contract-platform/get-contract.md): Get a single contract that you've imported or deployed. Retrieved using the contracts ID as opposed to the on-chain address.
- [Update a contract](https://developers.circle.com/api-reference/contracts/smart-contract-platform/update-contract.md): Update the off-chain properties, such as description, of a contract that you've imported or deployed. Updated using the contracts ID as opposed to the on-chain address.

##### Deploy / Import

- [Import a contract](https://developers.circle.com/api-reference/contracts/smart-contract-platform/import-contract.md): Add an existing smart contract to your library of contracts. It also can be done in the Developer Services Console.
- [Estimate a contract deployment](https://developers.circle.com/api-reference/contracts/smart-contract-platform/estimate-contract-deploy.md): Estimate the network fee for deploying a smart contract on a specified blockchain, given the contract bytecode.
- [Deploy a contract](https://developers.circle.com/api-reference/contracts/smart-contract-platform/deploy-contract.md): Deploy a smart contract on a specified blockchain using the contract's ABI and bytecode. The deployment will originate from one of your Circle Wallets.

##### Event Monitors

- [Get Event Monitors](https://developers.circle.com/api-reference/contracts/smart-contract-platform/get-event-monitors.md): Fetch a list of event monitors, optionally filtered by blockchain, contract address, and event signature.
- [Create Event Monitor](https://developers.circle.com/api-reference/contracts/smart-contract-platform/create-event-monitor.md): Create a new event monitor based on the provided blockchain, contract address, and event signature.
- [Update an Event Monitor](https://developers.circle.com/api-reference/contracts/smart-contract-platform/update-event-monitor.md): Update an existing event monitor given its ID.
- [Delete Event Monitor](https://developers.circle.com/api-reference/contracts/smart-contract-platform/delete-event-monitor.md): Delete an existing event monitor given its ID.
- [Get Event Logs](https://developers.circle.com/api-reference/contracts/smart-contract-platform/list-event-logs.md): Fetch all event logs, optionally filtered by blockchain and contract address.

### CCTP

- [CCTP API](https://developers.circle.com/api-reference/cctp.md): Fetch attestations and support crosschain transfers of USDC, EURC, and registered third-party assets using Cross-Chain Transfer Protocol.

#### CCTP

##### CCTP V1 (Legacy)

- [Get an attestation](https://developers.circle.com/api-reference/cctp/all/get-attestation.md): Retrieves the signed attestation for a USDC burn event on the source chain.
- [List attestation public keys](https://developers.circle.com/api-reference/cctp/all/get-public-keys.md): Retrieves a list of the currently active public keys for verifying attestation signatures.
- [Get a list of messages](https://developers.circle.com/api-reference/cctp/all/get-messages.md): Retrieves message and attestation details for CCTP V1 messages.

##### CCTP

- [Get public keys](https://developers.circle.com/api-reference/cctp/all/get-public-keys-v2.md): Returns the public keys for validating attestations across all supported versions of CCTP.
- [Get messages and attestations](https://developers.circle.com/api-reference/cctp/all/get-messages-v2.md): Retrieves messages and attestations for a given transaction hash or nonce. Each message for a given transaction hash is ordered by ascending log index.
- [Re-attest a pre-finality message](https://developers.circle.com/api-reference/cctp/all/reattest-message.md): The re-attestation flow allows the relayer to obtain a higher level of finality than was originally requested on the source chain, while still being forced to pay the fee since allowance was reserved. This flow resolves the case where a sender specifies a finality threshold lower than the destinatio…
- [Get USDC Fast Transfer allowance](https://developers.circle.com/api-reference/cctp/all/get-fast-burn-usdc-allowance.md): Retrieves the available USDC Fast Transfer allowance remaining.
- [Get USDC transfer fees](https://developers.circle.com/api-reference/cctp/all/get-burn-usdc-fees.md): Retrieves the applicable fees for a USDC transfer between the specified source and destination domains. The fee is returned in basis points (1 = 0.01%).

##### Quotes

- [Create a USDC transfer quote](https://developers.circle.com/api-reference/cctp/all/create-usdc-burn-quote.md): Returns a signed, time-bound fee quote for a native USDC transfer. A quote prices the fees a caller must pay and includes a `signedQuote` blob that the `TokenMessengerWithFees` contract verifies onchain.

### Gateway

- [Gateway API](https://developers.circle.com/api-reference/gateway.md): Access and manage a unified USDC balance across multiple blockchains with instant transfers in under 500 ms.

#### Gateway

##### Gateway

- [Get token balances for specified addresses](https://developers.circle.com/api-reference/gateway/all/get-token-balances.md): Returns the current available balance of each specified address across different domains where that address is valid
- [Estimate fees and expiration block heights for a transfer](https://developers.circle.com/api-reference/gateway/all/estimate-transfer.md): Calculates the required fees and expiration block heights for a transfer without requiring signatures or executing the transaction.
- [Get Gateway info for supported domains and tokens](https://developers.circle.com/api-reference/gateway/all/get-gateway-info.md): Provides information about the API and details of the supported domains and tokens.
- [Create a transfer attestation for transferring tokens](https://developers.circle.com/api-reference/gateway/all/create-transfer-attestation.md): Generates a transfer attestation and operator signature for transferring tokens between domains
- [Get a transfer by ID](https://developers.circle.com/api-reference/gateway/all/get-transfer-by-id.md): Returns detailed information about a transfer.
- [Get full TransferSpec by transferSpecHash](https://developers.circle.com/api-reference/gateway/all/get-transfer-spec.md): Retrieve the full TransferSpec for a given transferSpecHash.
- [Get pending deposits for specified addresses](https://developers.circle.com/api-reference/gateway/all/get-deposits.md): Returns pending deposits for each specified depositor address across different domains where that address is valid.

##### Gateway Batch

- [Submit an EIP-3009 authorization to be batched](https://developers.circle.com/api-reference/gateway/all/submit-batch-authorization.md): Submit a single-chain transfer authorization using EIP-3009 signature. The authorization will be verified, the sender's balance locked, and the transaction queued for batch processing.

##### Webhook Subscriptions

- [Get all webhook subscriptions](https://developers.circle.com/api-reference/gateway/all/get-permissionless-subscriptions.md): Retrieve an array of existing permissionless webhook subscriptions.
- [Create a webhook subscription](https://developers.circle.com/api-reference/gateway/all/create-permissionless-subscription.md): Create a permissionless webhook subscription by configuring an endpoint to receive event notifications. Specify the environment, wallet addresses to monitor, blockchain domains to watch, and event types to receive.
- [Retrieve a webhook subscription](https://developers.circle.com/api-reference/gateway/all/get-permissionless-subscription.md): Retrieve an existing permissionless webhook subscription.
- [Update a webhook subscription](https://developers.circle.com/api-reference/gateway/all/update-permissionless-subscription.md): Update a webhook subscription. Metadata fields can be updated independently. To update filters, provide `notificationTypes`, `addresses`, and `domains` together; those fields fully replace the existing filters.
- [Delete a webhook subscription](https://developers.circle.com/api-reference/gateway/all/delete-permissionless-subscription.md): Delete an existing permissionless webhook subscription.
- [Test subscription connection](https://developers.circle.com/api-reference/gateway/all/test-permissionless-subscription-connection.md): Verify that the subscriber endpoint for the given subscription is reachable.
- [Send a test notification](https://developers.circle.com/api-reference/gateway/all/send-permissionless-subscription-test-notification.md): Send a test notification to the subscriber endpoint. The notification has notificationType "webhooks.test".
- [Get a notification signature public key](https://developers.circle.com/api-reference/gateway/all/get-permissionless-notification-signature.md): Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

### x402 facilitators

- [x402 facilitators API](https://developers.circle.com/api-reference/x402-facilitators.md): Verify and settle USDC payments over the x402 protocol using Circle's Facilitator Service or Gateway Nanopayments.

#### Facilitator Service

##### Payments

- [Verify an x402 payment](https://developers.circle.com/api-reference/facilitator-service/verify-payment.md): Validates an x402 payment payload without creating a payment, consuming keyless trial usage, or submitting anything onchain. Use this endpoint for verification purposes. To settle a payment, see [Settle an x402 payment](/api-reference/agent-stack/facilitator-service/settle-payment).
- [Settle an x402 payment](https://developers.circle.com/api-reference/facilitator-service/settle-payment.md): Settles an x402 payment. Facilitator Service validates the buyer's EIP-3009 authorization, screens both parties, records the payment, and submits the USDC transfer through a Circle relayer.
- [Get payment status](https://developers.circle.com/api-reference/facilitator-service/get-payment-status.md): Returns the current status of a payment. Use this endpoint to reconcile a payment that settlement left unresolved with `errorReason: settlement_pending`.

##### Supported payment kinds

- [Get supported x402 payment kinds](https://developers.circle.com/api-reference/facilitator-service/get-supported.md): Returns the x402 payment kinds and extensions Facilitator Service accepts.

#### Gateway Nanopayments

##### Settlement

- [Settle an x402 payment](https://developers.circle.com/api-reference/gateway-nanopayments/settle-x402payment.md): Settles an x402 payment by submitting the EIP-3009 authorization. The authorization will be verified, the sender's balance locked, and the transaction queued for batch processing.
- [Verify an x402 payment payload](https://developers.circle.com/api-reference/gateway-nanopayments/verify-x402payment.md): Verifies that an x402 payment payload can be processed by running all read-only validation checks (scheme, network, token, signature, temporal constraints, address/amount matching). A valid result does not guarantee settlement — balance and nonce checks only happen at settle time.

##### Batched transfers

- [Search x402 transfers](https://developers.circle.com/api-reference/gateway-nanopayments/search-x402transfers.md): Returns a paginated list of x402 transfers matching the given filters. Supports cursor-based pagination via pageAfter / pageBefore.
- [Get an x402 transfer by ID](https://developers.circle.com/api-reference/gateway-nanopayments/get-x402transfer-by-id.md): Retrieves a single x402 transfer by its unique identifier.

##### Supported payment kinds

- [Get supported x402 payment kinds](https://developers.circle.com/api-reference/gateway-nanopayments/get-supported-x402payment-kinds.md): Returns the payment kinds supported by Circle Gateway for x402 batching.

### End User Onboarding

- [End User Onboarding API](https://developers.circle.com/api-reference/end-user-onboarding.md): Create and manage onboarding applications for business customers.
- [End User Onboarding API error codes](https://developers.circle.com/api-reference/end-user-onboarding/error-codes.md): Numeric error codes returned by the End User Onboarding API, with HTTP status, public message, and partner action.

#### End User Onboarding

##### Partner clients

- [Create a partner client](https://developers.circle.com/api-reference/end-user-onboarding/create-partner-client.md): Creates a new client entity and initializes an onboarding application in a single request. The response contains both the `clientEntityId` and the `applicationId` for the newly created draft application.
- [Get a partner client](https://developers.circle.com/api-reference/end-user-onboarding/get-partner-client.md): Returns a single client by its `clientEntityId`, scoped to your partner account. Requesting a client that does not exist — or one that belongs to a different partner — returns a `404 Not Found` error.
- [List partner clients](https://developers.circle.com/api-reference/end-user-onboarding/list-partner-clients.md): Retrieves the clients created under your partner account, newest first. Results are cursor-paginated, forward-only, via the `Link` response header. Each item always carries the `clientEntityId` and `created` timestamp. The profile fields (`clientName`, `country`, `clientType`, `businessDetails`) ech…

##### Partner applications

- [List applications for the authenticated partner](https://developers.circle.com/api-reference/end-user-onboarding/list-applications.md)
- [Retrieve an application by ID](https://developers.circle.com/api-reference/end-user-onboarding/get-application.md)
- [Cancel an application](https://developers.circle.com/api-reference/end-user-onboarding/cancel-application.md): Cancels a draft ONBOARDING_APPLICATION. Other operation types are not currently cancellable.
- [Save data for multiple sections in a single request](https://developers.circle.com/api-reference/end-user-onboarding/bulk-save.md): Accepts a JSON object keyed by section name. Each value is the same payload shape as PUT /sections/{sectionName}. Validation is atomic: all sections are validated before any data is saved, and if any section fails validation the entire request is rejected. Saves are sequential: after validation pass…
- [Retrieve data for all visible sections](https://developers.circle.com/api-reference/end-user-onboarding/get-all-data.md): Returns all visible section data keyed by section name alongside section statuses. The data object is round-trip compatible with PATCH /{applicationId}/data. Sections that do not contribute to application progress are excluded.
- [Get the JSON Schema (draft 2020-12) for an application's template](https://developers.circle.com/api-reference/end-user-onboarding/get-application-schema.md)
- [List active certifications for an application](https://developers.circle.com/api-reference/end-user-onboarding/get-certifications.md): Returns the active certifications the end user must agree to for this application, including the HTML content, certification id, and metadata. Pass the returned ids back on POST /{applicationId}/submit as certificationIds to explicitly acknowledge them, or omit certificationIds to let the service au…
- [Submit an application](https://developers.circle.com/api-reference/end-user-onboarding/submit-application.md)

##### Partner documents

- [List documents for an application](https://developers.circle.com/api-reference/end-user-onboarding/list-documents.md)
- [Upload a document for an application](https://developers.circle.com/api-reference/end-user-onboarding/upload-document.md)
- [Download a document](https://developers.circle.com/api-reference/end-user-onboarding/download-document.md)
- [Delete a document](https://developers.circle.com/api-reference/end-user-onboarding/delete-document.md)

##### Partner RFIs

- [List RFI bundles for an application](https://developers.circle.com/api-reference/end-user-onboarding/list-rfis.md)
- [Get RFI detail with comment history](https://developers.circle.com/api-reference/end-user-onboarding/get-rfi.md)
- [Submit field data in response to an UPDATE_FIELD or NEW_FIELD RFI](https://developers.circle.com/api-reference/end-user-onboarding/update-rfidata.md)
- [Add a comment to an RFI](https://developers.circle.com/api-reference/end-user-onboarding/create-comment.md)
- [Update a comment on an RFI](https://developers.circle.com/api-reference/end-user-onboarding/update-comment.md)
- [Delete a comment on an RFI](https://developers.circle.com/api-reference/end-user-onboarding/delete-comment.md)

##### Partner sections

- [List sections for an application](https://developers.circle.com/api-reference/end-user-onboarding/list-sections.md): Returns visible sections with statuses. When includeData=true, each entry also includes the section's current field data — useful for rendering a progress view alongside prefilled form data. When typedValues=true (only meaningful with includeData=true), array/object/number field values are emitted a…
- [Retrieve section data for an application](https://developers.circle.com/api-reference/end-user-onboarding/get-section.md): Returns field data for the specified section. When typedValues=true, array/object/number field values are emitted as native JSON nodes instead of strings.
- [Save section data for an application](https://developers.circle.com/api-reference/end-user-onboarding/save-section.md): Saves field data for a section. The request body is a JSON object whose shape is defined by the section's JSON Schema (retrieve it via GET /{applicationId}/schema). For MULTIPLE array sections, maxItems is enforced and over-limit payloads return 422.
- [Remove an entity from an array section](https://developers.circle.com/api-reference/end-user-onboarding/remove-entity.md)

### StableFX

- [StableFX API](https://developers.circle.com/api-reference/stablefx.md): Request quotes and execute institutional FX trades between supported currencies with onchain settlement on Arc.
- [Postman collection](https://developers.circle.com/api-reference/stablefx/postman.md): Use Circle's Postman collection to send API requests and explore the StableFX APIs.
- [StableFX API rate limits](https://developers.circle.com/api-reference/stablefx/rate-limits.md): Per-entity rate limits and throttling behavior for all StableFX API endpoints.

#### StableFX

##### Quotes

- [Create a quote](https://developers.circle.com/api-reference/stablefx/all/create-quote.md): Creates a quote for a trade between two currencies. You should provide an `amount` for the `from` parameter or the `to` parameter, but not for both. Use `type:tradable` for an executable quote or `type:reference` for an indicative quote. Tradable quotes include presign `typedData` for signing.

##### Trades

- [Get all trades](https://developers.circle.com/api-reference/stablefx/all/list-trades.md): Returns a cursor-paginated list of all trades, newest first by default.
- [Create a trade](https://developers.circle.com/api-reference/stablefx/all/create-trade.md): Accepts a quote and creates a trade.
- [Get a trade](https://developers.circle.com/api-reference/stablefx/all/get-trade-by-id.md): Returns a trade specified by the ID path parameter

##### Signatures

- [Register a trade signature](https://developers.circle.com/api-reference/stablefx/all/register-trade-signature.md): Registers a signed EIP-712 payload from the trader that confirms trade intent.
- [Generate trade presign data](https://developers.circle.com/api-reference/stablefx/all/generate-trade-signature-data.md): Returns the EIP-712 Permit2 payload that the maker must sign for a trade.
- [Generate funding presign data](https://developers.circle.com/api-reference/stablefx/all/generate-funding-presign-data.md): Returns the Permit2 EIP-712 payload that the trader must sign for funding operations. `fundingMode` net and net_delegate options are supported for maker funding requests only.
- [Get settlement advance Permit2 typed data for signing](https://developers.circle.com/api-reference/stablefx/all/presign-settlement-advance.md): Returns Permit2 typed-data the maker signs to authorize delegate funding of their side of a trade. The witness is a `DelegateFundingAuthorization` with `permitted.amount = 0` -- Permit2 is used purely as an authorization carrier, no tokens transfer from the maker.

##### Fees

- [Get fee for a trade](https://developers.circle.com/api-reference/stablefx/all/get-trade-fee.md): Returns the fee associated with the trade ID provided in the path parameter.

##### Funding

- [Fund trades](https://developers.circle.com/api-reference/stablefx/all/fund-trade.md): Executes funding for trades using Permit2 signatures. This endpoint relays the signed permit data to complete the funding operation for trades.

##### Webhooks

- [Trade confirmed](https://developers.circle.com/api-reference/stablefx/all/trade-confirmed.md): The StableFX trade has been confirmed by the exchange.
- [Trade pending settlement](https://developers.circle.com/api-reference/stablefx/all/trade-pending-settlement.md): The StableFX trade has been confirmed onchain and is awaiting funding from taker and maker.
- [Trade maker funded](https://developers.circle.com/api-reference/stablefx/all/trade-maker-funded.md): The maker has funded their side of the trade. The maker's fund delivery transaction has been confirmed onchain.
- [Trade taker funded](https://developers.circle.com/api-reference/stablefx/all/trade-taker-funded.md): The taker has funded their side of the trade. The taker's fund delivery transaction has been confirmed onchain.
- [Trade completed](https://developers.circle.com/api-reference/stablefx/all/trade-completed.md): The StableFX trade has been completed successfully. Both the maker and the taker have funded their side and the trade is fully settled.
- [Trade refunded](https://developers.circle.com/api-reference/stablefx/all/trade-refunded.md): The StableFX trade has been refunded.
- [Trade failed](https://developers.circle.com/api-reference/stablefx/all/trade-failed.md): The StableFX trade has failed.
- [Trade breached](https://developers.circle.com/api-reference/stablefx/all/trade-breached.md): The StableFX trade has breached its maturity date.
- [Record trade operation failed](https://developers.circle.com/api-reference/stablefx/all/contract-record-trade-failed.md): The record trade operation on the contract has failed. The initial onchain recording of the trade was unsuccessful.
- [Maker deliver operation failed](https://developers.circle.com/api-reference/stablefx/all/contract-maker-deliver-failed.md): The maker deliver operation on the contract has failed. The maker's deliver transaction failed to confirm onchain.
- [Taker deliver operation failed](https://developers.circle.com/api-reference/stablefx/all/contract-taker-deliver-failed.md): The taker deliver operation on the contract has failed. The taker's deliver transaction failed to confirm onchain.
- [Trade maker delegate funded](https://developers.circle.com/api-reference/stablefx/all/trade-maker-delegate-funded.md): The maker leg has been funded via a delegated funder. Distinct from makerFunded so subscribers can tell direct-funded legs apart from delegate-funded legs.
- [Trade taker delegate funded](https://developers.circle.com/api-reference/stablefx/all/trade-taker-delegate-funded.md): The taker leg has been funded via a delegated funder. Distinct from takerFunded so subscribers can tell direct-funded legs apart from delegate-funded legs.
- [Contract maker delegate deliver failed](https://developers.circle.com/api-reference/stablefx/all/contract-maker-delegate-deliver-failed.md): The maker's delegated funding transaction failed on-chain.
- [Contract taker delegate deliver failed](https://developers.circle.com/api-reference/stablefx/all/contract-taker-delegate-deliver-failed.md): The taker's delegated funding transaction failed on-chain.

##### Webhook Subscriptions

- [Get all webhook subscriptions](https://developers.circle.com/api-reference/stablefx/all/get-subscriptions.md): Returns an array of all webhook subscriptions.
- [Create a webhook subscription](https://developers.circle.com/api-reference/stablefx/all/create-subscription.md): Create a webhook subscription by configuring an endpoint to receive notifications.
- [Get a notification subscription](https://developers.circle.com/api-reference/stablefx/all/get-subscription.md): Returns an existing notification subscription.
- [Update a notification subscription](https://developers.circle.com/api-reference/stablefx/all/update-subscription.md): Update a notification subscription by configuring an endpoint to receive notifications.
- [Delete a notification subscription](https://developers.circle.com/api-reference/stablefx/all/delete-subscription.md): Delete an existing subscription.
- [Get a notification signature public key](https://developers.circle.com/api-reference/stablefx/all/get-notification-signature.md): Get the public key and algorithm used to digitally sign webhook notifications. Verifying the digital signature ensures the notification came from Circle.

##### Settlement Advance

- [Get settlement advance credit line](https://developers.circle.com/api-reference/stablefx/all/get-settlement-advance-credit.md): Returns the maker's settlement-advance credit line including total limit, current usage, available headroom per currency, and the applicable fee schedule (recurring, draw, and reservation fees).
- [Reserve settlement advance credit](https://developers.circle.com/api-reference/stablefx/all/reserve-settlement-advance.md): Holds credit so the maker can lock in a fee snapshot before requesting the settlement advance. Reservations expire after a short window (~15 minutes); after expiry the maker must reserve again.
- [List settlement advance reservations](https://developers.circle.com/api-reference/stablefx/all/list-settlement-advance-reservations.md): Returns the maker's settlement advance reservations, optionally filtered by status and currency. Supports cursor-based pagination, newest first.
- [Get a settlement advance reservation](https://developers.circle.com/api-reference/stablefx/all/get-settlement-advance-reservation.md): Returns a single settlement advance reservation by ID.
- [Cancel a settlement advance reservation](https://developers.circle.com/api-reference/stablefx/all/cancel-settlement-advance-reservation.md): Cancels an active settlement advance reservation, releasing the held credit back to the line. Only reservations in `active` status can be canceled.
- [List settlement advances](https://developers.circle.com/api-reference/stablefx/all/list-settlement-advances.md): Returns the maker's settlement advances with their lifecycle status, filterable by status and date range. Supports cursor-based pagination.
- [Request a settlement advance](https://developers.circle.com/api-reference/stablefx/all/request-settlement-advance.md): Submit the Permit2 signature generated from the presign endpoint along with the witness payload. Funding runs asynchronously after this call returns.
- [Get settlement advance detail](https://developers.circle.com/api-reference/stablefx/all/get-settlement-advance-detail.md): Returns the full detail of a single settlement advance including its lifecycle status, advance and collateral amounts, fee information, and any repayments applied.
- [Repay a settlement advance](https://developers.circle.com/api-reference/stablefx/all/repay-settlement-advance.md): Records a repayment against the credit line backing a settlement advance. Any excess would be balance of the Circle Mint account.
- [Get a settlement advance repayment](https://developers.circle.com/api-reference/stablefx/all/get-settlement-advance-repayment.md): Returns the details of a specific settlement advance repayment.

### xReserve

- [xReserve API](https://developers.circle.com/api-reference/xreserve.md): Deposit USDC into xReserve, retrieve attestations, and manage withdrawals for USDC-backed stablecoins.

#### xReserve

- [Get attestations by source transaction hash](https://developers.circle.com/api-reference/xreserve/all/get-attestations-by-tx-hash.md): Returns all attestations associated with the specified source chain transaction hash. A single transaction may produce multiple attestations across different remote domains.
- [Get an attestation for a crosschain transfer](https://developers.circle.com/api-reference/xreserve/all/get-attestation.md): Returns the attestation for a specified crosschain transfer using the deposit message hash.
- [List attestations for crosschain transfers](https://developers.circle.com/api-reference/xreserve/all/list-attestations.md): Returns an array of attestations for the specified crosschain transfers, filtered by remote domain.
- [Get token balances on a remote domain](https://developers.circle.com/api-reference/xreserve/all/get-balances.md): Returns the expected token balances for a specified remote domain based on the deposit amounts made into xReserve.
- [Get domain information](https://developers.circle.com/api-reference/xreserve/all/get-info.md): Returns information on source and remote domains, including its supported tokens and configuration details.
- [Prepare a withdrawal request](https://developers.circle.com/api-reference/xreserve/all/prepare-withdrawal.md): Turns the user's burn transaction data on the remote chain into fully encoded burn intents to send to the `/withdraw` endpoint. This endpoint performs the following: - Resolves contract and token addresses across networks. - Determines the optimal forwarding strategy, such as redepositing to another…
- [Submit signed burn intents for withdrawal](https://developers.circle.com/api-reference/xreserve/all/submit-withdrawal.md): Submits up to five signed burn intent batches per request call. Each batch may contain one burn intent or a set of up to 10.
- [Get withdrawal status](https://developers.circle.com/api-reference/xreserve/all/get-withdrawal-status.md): Returns the status and transfer details of a specified withdrawal group.

### Match

#### Match

##### Account

- [Get account summary](https://developers.circle.com/api-reference/circle-match/all/get-account.md): Returns a best-effort snapshot of your Circle Match USDC balance, open-order exposure, and windowed activity totals. Use this for pre-order balance checks and dashboard display. For exact reconciliation, use your order and settlement records instead.

##### Orders

- [List orders](https://developers.circle.com/api-reference/circle-match/all/list-orders.md): Returns a paginated list of your orders. All query parameters are optional. An unrecognised `status` or `orderType` value returns 400. Passing `from` after `to` returns 400.
- [Place an order](https://developers.circle.com/api-reference/circle-match/all/place-order.md): Submits a BURN or MINT order to the current auction cycle. Returns 202 Accepted with the orderId and initial `pending` status. The order rests until the auction clears. The `idempotencyKey` you supply becomes the `orderId` for all subsequent lookups. Use a unique UUID v4 per order. Reusing a key wit…
- [Get an order](https://developers.circle.com/api-reference/circle-match/all/get-order.md): Returns full detail for a single order, including lineage fields for tracing rolled orders and a fill object that is populated after matching. Follow `lineage.parentOrderId` backward or `lineage.childOrderId` forward to reconstruct the full chain for a rolled order.
- [Cancel an order](https://developers.circle.com/api-reference/circle-match/all/cancel-order.md): Cancels a single resting order. Cancellations are blocked during the lock window (error 136001) and while the previous auction is settling (error 136002). If the order has already cleared, it cannot be cancelled.
- [Cancel all orders](https://developers.circle.com/api-reference/circle-match/all/cancel-all-orders.md): Cancels every resting order you hold in the current auction cycle. No request body is required. Returns 200 with an empty `orderIds` array if you have no resting orders. Blocked during the lock window (error 136001).
- [Modify an order](https://developers.circle.com/api-reference/circle-match/all/modify-order.md): Changes the fee limit on a resting order. Only the fee changes; the order remains in `pending` status with its original size and side. Outside the lock window, the fee can move in either direction. During the lock window, the new value must be more competitive than the current value (lower for BURN…

##### Withdrawals

- [Withdraw funds](https://developers.circle.com/api-reference/circle-match/all/create-withdrawal.md): Converts your Circle-Match-only USDC balance to USD and wires it to the specified fiat account. This exit path is for mint-side participants only; burn-side USDC releases automatically when orders fill or are cancelled. No Circle Mint burn fee applies.

##### WebSocket

- [Create a WebSocket ticket](https://developers.circle.com/api-reference/circle-match/all/create-ws-ticket.md): Issues a short-lived JWT for authenticating a WebSocket connection. The token is validated on signature, issuer, audience, and expiry. Obtain it immediately before opening the socket — it expires at `expiresAt`. Connect to the WebSocket endpoint using two `Sec-WebSocket-Protocol` values: - `circle-m…

## OpenAPI Specs

- [openapi-public](/openapi/openapi-public.yaml)
- [configurations_2](/openapi/configurations_2.yaml)
- [configurations_1](/openapi/configurations_1.yaml)
- [developer-controlled-wallets](/openapi/developer-controlled-wallets.yaml)
- [user-controlled-wallets](/openapi/user-controlled-wallets.yaml)
- [buidl-wallets](/openapi/buidl-wallets.yaml)
- [compliance](/openapi/compliance.yaml)
- [smart-contract-platform](/openapi/smart-contract-platform.yaml)
- [cctp](/openapi/cctp.yaml)
- [gateway](/openapi/gateway.yaml)
- [facilitator-service](/openapi/facilitator-service.yaml)
- [gateway-nanopayments](/openapi/gateway-nanopayments.yaml)
- [accounts](/openapi/accounts.yaml)
- [customer-orchestration](/openapi/customer-orchestration.yaml)
- [partner-openapi](/openapi/partner-openapi.yaml)
- [account](/openapi/account.yaml)
- [general](/openapi/general.yaml)
- [institutional](/openapi/institutional.yaml)
- [cross-currency](/openapi/cross-currency.yaml)
- [reserve-management](/openapi/reserve-management.yaml)
- [credit](/openapi/credit.yaml)
- [digital-asset-backed-borrowing](/openapi/digital-asset-backed-borrowing.yaml)
- [payments](/openapi/payments.yaml)
- [payouts](/openapi/payouts.yaml)
- [configurations](/openapi/configurations.yaml)
- [cpn-ofi](/openapi/cpn-ofi.yaml)
- [managed-payments](/openapi/managed-payments.yaml)
- [managed-payments-webhooks](/openapi/managed-payments-webhooks.yaml)
- [stablefx](/openapi/stablefx.yaml)
- [xreserve](/openapi/xreserve.yaml)
- [match](/openapi/match.yaml)