> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. > ## 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. # List all crypto payments > Lists all crypto payments and crypto refunds. ## OpenAPI ````yaml openapi/accounts.yaml get /v1/payments openapi: 3.1.0 info: version: 1.0.0 title: Accounts (Stablecoin) API description: > Circle's Accounts API provides endpoints for managing stablecoin accounts -- including transfers, withdrawals, deposits, wire and ACH bank accounts, and blockchain addresses. An **Account** is a general representation of a ledger or custody object that holds balances. It can be a business account, a stablecoin account ledger for an end user, an extra sub-ledger, or any future custody solution. license: name: Circle License url: https://circle.com/terms servers: - url: https://api-sandbox.circle.com - url: https://api.circle.com security: [] tags: - name: Accounts description: Manage accounts. - name: Account Groups description: Manage custody account groups and their memberships. - name: Limits description: View effective account limits and current usage. - name: Transfers description: Manage account transfers. - name: Transactions description: | Get a unified, customer-friendly view of account transaction activity. - name: Wires description: Manage account bank accounts for wire transfers. - name: Deposits description: Get information on account bank deposits. - name: Withdrawals description: Manage account bank withdrawals (fiat offramp). - name: ACH description: Manage account bank accounts for ACH transfers. - name: Deposit Addresses description: Manage account deposit addresses. - name: Recipient Addresses description: Manage account recipient addresses used for transfers. - name: Passkeys description: > Manage WebAuthn passkeys and Strong Customer Authentication (SCA) challenges for end users. - name: Crypto Payments description: > Get crypto payments and crypto refunds received through payment intents. Available for Digital Asset Accounts only on custody accounts (`purpose: custody`), and only for third-party payments. Not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. - name: Crypto Payment Intents description: > Create, expire, refund, and track payment intents for receiving crypto payments. Available for Digital Asset Accounts only on custody accounts (`purpose: custody`), and only for third-party payments. Not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. - name: Crypto Payouts description: > Create and track crypto payouts to recipient addresses. Available for Digital Asset Accounts only on custody accounts (`purpose: custody`), and only for third-party payouts. Not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. - name: Crypto Address Book description: > Manage address book recipients used as crypto payout destinations. Available for Digital Asset Accounts only on custody accounts (`purpose: custody`), and only for third-party payouts. Not supported when the distributor or the end user is under the Circle FR (`CIRCLE_FR`) or Circle SG (`CIRCLE_SG`) legal entity. - name: Webhook Subscriptions description: Manage subscriptions to Digital Asset Accounts webhook notifications. paths: /v1/payments: get: tags: - Crypto Payments summary: List all crypto payments description: Lists all crypto payments and crypto refunds. operationId: listPayments parameters: - name: paymentIntentId description: Queries items with the specified payment intent ID. in: query required: false schema: type: string format: uuid example: b48c8962-8e9f-40c3-9f1d-d9adde2ffe61 - name: paymentType description: >- Payment resource type. Filters the results to fetch only payments or only refunds. Matches any type if unspecified. in: query required: false schema: type: array uniqueItems: true items: type: string enum: - payment - refund - name: status description: >- Queries items with the specified status. Matches any status if unspecified. in: query required: false schema: $ref: '#/components/schemas/PaymentStatus' - name: walletId description: > The `accountId` of the custody account to list payments for. Without this filter, a Digital Asset Accounts distributor key returns only payments on the distributor's own entity. To list an end user's payments, pass the `accountId` of the end user's custody account. The account must belong to the caller; otherwise the request is rejected. in: query required: false schema: type: string example: '1000662322' - $ref: '#/components/parameters/From' - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/PageBefore' - $ref: '#/components/parameters/PageAfter' - $ref: '#/components/parameters/PageSize' responses: '200': description: Successfully retrieved a list of payments. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ListPaymentsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: PaymentStatus: type: string description: > Enumerated status of the payment. `pending` means the payment is waiting to be processed. `confirmed` means the payment has been approved and the merchant can treat it as successful, but settlement funds are not yet available to the merchant. `paid` means settlement funds have been received and are available to the merchant. `failed` means something went wrong. `action_required` means that additional steps are required to process this payment. Terminal states are `paid` and `failed`. enum: - pending - confirmed - paid - failed - action_required ListPaymentsResponse: title: ListPaymentsResponse properties: data: type: array items: $ref: '#/components/schemas/CryptoPayment' UtcTimestamp: type: string description: ISO-8601 UTC date/time format. example: '2020-04-10T02:13:30.000Z' XRequestId: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde CryptoPayment: type: object description: A crypto payment or crypto refund. required: - id - type - merchantId - amount - status properties: id: $ref: '#/components/schemas/Id' type: description: Type of the payment object. type: string enum: - payment - refund merchantId: $ref: '#/components/schemas/MerchantId' merchantWalletId: $ref: '#/components/schemas/MerchantWalletId' amount: $ref: '#/components/schemas/CryptoPaymentsOptionalAmountMoney' status: $ref: '#/components/schemas/PaymentStatus' statusReason: $ref: '#/components/schemas/CryptoPaymentStatusReason' errorCode: $ref: '#/components/schemas/CryptoPaymentErrorCode' fees: $ref: '#/components/schemas/FiatMoneyUsd' networkFees: $ref: '#/components/schemas/CryptoPaymentNetworkFee' paymentIntentId: type: string format: uuid example: 6e4d4047-db14-4c09-b238-1215aee50d03 customerExternalRef: $ref: '#/components/schemas/PaymentCustomerExternalRef' settlementAmount: $ref: '#/components/schemas/CryptoPaymentsMoney' fromAddresses: type: object properties: chain: $ref: '#/components/schemas/Chain' addresses: type: array items: $ref: '#/components/schemas/Address' depositAddress: type: object properties: chain: $ref: '#/components/schemas/Chain' address: type: string example: '0x97de855690955e0da79ce5c1b6804847e7070c7f' addressTag: $ref: '#/components/schemas/AddressTag' transactionHash: type: string example: '0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906' refundIds: description: >- List of refunds associated with this payment. Only populated when `type` is `payment`. type: array items: type: string format: uuid example: 8edc0da8-d086-3051-a393-53f972d16444 paymentId: type: string format: uuid description: >- Identifier of the payment this refund is attributed to. Only populated when `type` is `refund` and the refund was attributed to a specific payment. example: 36a25933-8c2d-3c23-ad07-7fe1e41b5fe5 createDate: $ref: '#/components/schemas/UtcTimestamp' updateDate: $ref: '#/components/schemas/UtcTimestamp' riskEvaluation: $ref: '#/components/schemas/RiskEvaluation' Error: type: object required: - code - message properties: code: type: integer description: > Circle internal status code from the platform `CoreStatusCode` enum (and its domain-specific extensions). **This is not the HTTP status code** — `-1` is the catch-all unknown error, `1`/`2` indicate API parameter problems, `3` is forbidden, `4` is unauthorized, and larger values identify domain-specific failures. Consumers should rely on the HTTP status line for transport-level error class and on this field for the specific Circle error case. example: 2 message: type: string description: >- Internal error message; suitable for logging but not for end-user display. example: API parameter invalid. externalMessage: type: string description: > End-user-displayable error message. Present when the server has generated a customer-facing variant for this error; omitted otherwise. example: The provided amount exceeds the maximum allowed. errors: type: array description: Additional request-field validation errors, when available. items: $ref: '#/components/schemas/ErrorDetail' Id: type: string description: Unique system-generated identifier for the entity. format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 MerchantId: type: string description: Unique system-generated identifier for the merchant. format: uuid example: fc988ed5-c129-4f70-a064-e5beb7eb8e32 MerchantWalletId: type: string description: >- Identifier of the wallet that receives the payment. For Digital Asset Accounts, this is the `accountId` of the custody account. maxLength: 36 example: '1000662322' CryptoPaymentsOptionalAmountMoney: type: object required: - currency properties: amount: type: string description: Magnitude of the amount, in units of the currency, with a `.`. example: '3.14' currency: description: Currency code. type: string enum: - USD - EUR - ETH - BTC CryptoPaymentStatusReason: type: string description: > Provides additional context for certain payment statuses. | Status | Status Reason | Description | | --- | --- | --- | | `pending` | `compliance_review` | Compliance is awaiting PII before releasing funds. | | `failed` | `compliance_denied` | Funds seized due to sanctions hit. | | `failed` | `unsupported_wallet` | Funds are stuck in escrow because the sender wallet is not supported (self-hosted wallet or non-VASP). | | `paid` | `unsupported_wallet` | Funds have settled but were received from an unsupported VASP. | | `paid` or `pending` | `pii_not_received` | PII was not received within the Travel Rule window. | enum: - compliance_review - compliance_denied - unsupported_wallet - pii_not_received example: compliance_review CryptoPaymentErrorCode: type: - string - 'null' description: >- Indicates the failure reason of a crypto payment or refund. Only present when a failure reason is available. enum: - insufficient_funds - transaction_orphaned - payment_failed - null example: insufficient_funds FiatMoneyUsd: type: object required: - amount - currency properties: amount: type: string description: Magnitude of the amount, in units of the currency, with a `.`. example: '3.14' currency: description: Currency code. type: string enum: - USD CryptoPaymentNetworkFee: type: object required: - amount - currency properties: amount: type: string description: Magnitude of the amount, in units of the currency, with a `.`. example: '3.14' currency: type: string description: Currency code for the amount. enum: - USD - EUR - BTC - ETH feePayer: type: string description: The party that pays the network fee based on merchant configuration. enum: - endUser - merchant PaymentCustomerExternalRef: type: string format: uuid description: >- A customer-supplied reference for reconciliation purposes, used on payment intents, payments, and refunds. Must be a UUID. Payouts use a separate 36-character limit schema. example: 310c458a-18eb-4cbd-8a9a-586d9448ae69 CryptoPaymentsMoney: type: object required: - amount - currency properties: amount: type: string description: Magnitude of the amount, in units of the currency, with a `.`. example: '3.14' currency: description: Currency code. type: string enum: - USD - EUR Chain: type: string description: A blockchain that a given currency is available on. example: ETH enum: - ALGO - APTOS - ARB - ARC - AVAX - BASE - BTC - CELO - CODEX - ETH - HBAR - HYPEREVM - INK - LINEA - NEAR - NOBLE - OP - PLUME - PAH - POLY - SEI - SOL - SONIC - SUI - UNI - WORLDCHAIN - XDC - XLM - XRP - ZKS Address: type: string description: > An alphanumeric string representing a blockchain address. Formatting varies by blockchain. Be sure to preserve the exact formatting and capitalization of the address. example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F' AddressTag: type: - string - 'null' description: >- The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, ID, or hash format. example: '123456789' RiskEvaluation: type: - object - 'null' description: >- Results of risk evaluation. Only present if the payment is denied by Circle's risk service. properties: decision: description: Enumerated decision of the account. type: string enum: - approved - denied - review reason: description: Risk reason for the definitive decision outcome. type: - string - 'null' example: '3000' ErrorDetail: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. example: invalid_value location: type: string description: Query parameter or request field that caused the error. example: assetType message: type: string description: Human-readable description of the specific error. example: The operation and assetType combination is invalid. parameters: From: name: from description: >- Queries items created since the specified date-time (inclusive) in ISO 8601 format. in: query required: false schema: $ref: '#/components/schemas/UtcTimestamp' To: name: to description: >- Queries items created before the specified date-time (inclusive) in ISO 8601 format. in: query required: false schema: $ref: '#/components/schemas/UtcTimestamp' PageBefore: name: pageBefore description: >- A collection ID value used for pagination. It marks the exclusive end of a page. When provided, the collection resource will return the next `n` items before the id, with `n` being specified by `pageSize`. in: query required: false schema: type: string example: def9520a-5280-4089-9b02-3c9ef8fc8514 PageAfter: name: pageAfter description: >- A collection ID value used for pagination. It marks the exclusive beginning of a page. When provided, the collection resource will return the next `n` items after the id, with `n` being specified by `pageSize`. in: query required: false schema: type: string example: bce1e961-bdb8-4983-a9c2-0b3fbc2614cf PageSize: name: pageSize description: > Limits the number of items to be returned. Some collections have a strict upper bound that will disregard this value. In case the specified value is higher than the allowed limit, the collection limit will be used. If omitted, the collection will determine the page size itself. in: query required: false schema: type: integer minimum: 1 example: 5 headers: XRequestId: description: > Circle-generated universally unique identifier (UUID v4). Useful for identifying a specific request when communicating with Circle Support. schema: $ref: '#/components/schemas/XRequestId' responses: BadRequest: description: The request cannot be processed due to a client error. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 2 message: API parameter invalid. NotAuthorized: description: >- The request has not been applied because it lacks valid authentication credentials. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 4 message: Unauthorized. InternalServerError: description: >- The server encountered an unexpected condition that prevented it from fulfilling the request. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: -1 message: 'Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4' securitySchemes: bearerAuth: type: http scheme: bearer ````