> ## 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. # Request a report > Submits a report generation request. `reportType` specifies the type of report and required fields. Supported report types: `camt053`, `camt_managed`, `managed_payout_transactions`, `managed_payment_wallet_balances`, and `managed_payin_transactions`. The managed-payment reports take a `timeframe` field (`daily` or `monthly`); `camt_managed` and `managed_payment_wallet_balances` support `daily` only. If ready, returns `200` with a pre-signed `downloadUrl`. If not, returns `202` with status `pending`. Poll `GET /v1/reports/{id}` for status, or download using `GET /v1/reports/{id}/content` when ready. Requests are idempotent: the same entity and request parameters always produce the same report ID. Retries return the existing report. `camt053` reports are only returned for accounts with activity in the preceding 365 days. `camt_managed` reports are only generated for dates with managed payment activity. Requesting a date with no activity returns `400` (`{"code":2,"message":"API parameter invalid"}`), the same response as a malformed request. To discover which dates have reports before calling this endpoint, use `GET /v1/reports?reportType=camt_managed&startDate=&endDate=`. ## OpenAPI ````yaml openapi/account.yaml post /v1/reports openapi: 3.0.2 info: version: ${version} title: Core Functionality description: > All of Circle's APIs share a common set of core functionality that lets you manage your Circle Account in a programmatic way. With a Circle Account your business can deposit traditional money from 80+ countries and seamlessly convert them into "digital currency dollars": USDC. You can then use USDC for everyday payments and treasury flows. servers: - url: https://api-sandbox.circle.com - url: https://api.circle.com security: [] tags: - name: Balances description: Get information on settled and unsettled balances. - name: Payouts description: Create and get information on 1st party payouts. - name: Wires description: >- Create, get instructions, and get information on 1st party bank accounts for wire transfers. - name: CUBIX description: Create and get information on CUBIX accounts. - name: PIX description: Create and get information on PIX accounts. - name: Transfers description: Create and get information on 1st party transfers. - name: Addresses description: Generate and get information on blockchain addresses. - name: Deposits description: Get information on 1st party deposits. - name: Payments description: Create, cancel, refund, and get updates on card payments. - name: Settlement Bank Routing description: View and manage settlement bank routing preferences for fiat accounts. - name: Reporting description: >- Retrieve transaction and balance reports, including ISO 20022 (CAMT.053) statements and managed-payment reports. paths: /v1/reports: post: tags: - Reporting summary: Request a report description: > Submits a report generation request. `reportType` specifies the type of report and required fields. Supported report types: `camt053`, `camt_managed`, `managed_payout_transactions`, `managed_payment_wallet_balances`, and `managed_payin_transactions`. The managed-payment reports take a `timeframe` field (`daily` or `monthly`); `camt_managed` and `managed_payment_wallet_balances` support `daily` only. If ready, returns `200` with a pre-signed `downloadUrl`. If not, returns `202` with status `pending`. Poll `GET /v1/reports/{id}` for status, or download using `GET /v1/reports/{id}/content` when ready. Requests are idempotent: the same entity and request parameters always produce the same report ID. Retries return the existing report. `camt053` reports are only returned for accounts with activity in the preceding 365 days. `camt_managed` reports are only generated for dates with managed payment activity. Requesting a date with no activity returns `400` (`{"code":2,"message":"API parameter invalid"}`), the same response as a malformed request. To discover which dates have reports before calling this endpoint, use `GET /v1/reports?reportType=camt_managed&startDate=&endDate=`. operationId: requestReport requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReportRequest' examples: camt053: summary: CAMT.053 daily statement value: reportType: camt053 date: '2025-01-15' camtManaged: summary: Managed-payments CAMT.053 daily statement value: reportType: camt_managed timeframe: daily date: '2025-01-15' managedPayoutMonthly: summary: Monthly managed payout transactions value: reportType: managed_payout_transactions timeframe: monthly date: 2025-01 responses: '200': description: >- Report is ready. Use the pre-signed `downloadUrl` to download the file. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: title: RequestReportResponse properties: data: $ref: '#/components/schemas/ReportRecord' examples: camt053: summary: CAMT.053 daily statement value: data: id: 550e8400-e29b-41d4-a716-446655440000 reportType: camt053 status: ready downloadUrl: https://s3.amazonaws.com/... expiresAt: '2025-01-15T15:00:00Z' camtManaged: summary: Managed-payments CAMT.053 daily statement value: data: id: 550e8400-e29b-41d4-a716-446655440000 reportType: camt_managed status: ready downloadUrl: https://s3.amazonaws.com/... expiresAt: '2025-01-15T15:00:00Z' '202': description: > Report generation is in progress. Use `GET /v1/reports/{id}` to check the status. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: title: RequestReportAcceptedResponse properties: data: $ref: '#/components/schemas/ReportRecord' examples: camt053: summary: CAMT.053 daily statement value: data: id: 550e8400-e29b-41d4-a716-446655440000 reportType: camt053 status: pending camtManaged: summary: Managed-payments CAMT.053 daily statement value: data: id: 550e8400-e29b-41d4-a716-446655440000 reportType: camt_managed status: pending '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: ReportRequest: description: > Request body for generating a report. The `reportType` field determines the type of report and which additional fields are required. oneOf: - $ref: '#/components/schemas/Camt053StatementRequest' - $ref: '#/components/schemas/CamtManagedRequest' - $ref: '#/components/schemas/ManagedPayoutTransactionsRequest' - $ref: '#/components/schemas/ManagedPaymentWalletBalancesRequest' - $ref: '#/components/schemas/ManagedPayinTransactionsRequest' discriminator: propertyName: reportType mapping: camt053: '#/components/schemas/Camt053StatementRequest' camt_managed: '#/components/schemas/CamtManagedRequest' managed_payout_transactions: '#/components/schemas/ManagedPayoutTransactionsRequest' managed_payment_wallet_balances: '#/components/schemas/ManagedPaymentWalletBalancesRequest' managed_payin_transactions: '#/components/schemas/ManagedPayinTransactionsRequest' ReportRecord: type: object description: > Metadata for a unified report. `status` reflects whether the generated file is available. If `status` is `ready`, the response includes a pre-signed `downloadUrl`. If `pending`, generation is still in progress. Poll `GET /v1/reports/{id}` until `ready`, then download using `GET /v1/reports/{id}/content`. Requests are idempotent: the same entity and request parameters always produce the same report ID. Subsequent `POST` requests return the existing report. required: - id - reportType - status properties: id: type: string format: uuid description: > Unique, deterministic identifier for this report. The same entity and request parameters always produce the same ID. Safe to retry as subsequent POST requests return the same report. example: 550e8400-e29b-41d4-a716-446655440000 reportType: type: string enum: - camt053 - camt_managed - managed_payout_transactions - managed_payment_wallet_balances - managed_payin_transactions description: Report type identifier. example: camt053 status: type: string enum: - pending - ready - failed description: > Current lifecycle status of the report. - `ready`: Report is available to download. Use `downloadUrl` or the content endpoint. - `pending`: Report generation is in process. Poll `GET /v1/reports/{id}` until `ready`. - `failed`: Report generation failed. example: ready downloadUrl: type: string format: uri nullable: true description: | Pre-signed URL to download the report. Present only when status is `ready`; omitted otherwise. example: https://s3.amazonaws.com/... expiresAt: type: string format: date-time nullable: true description: > Expiration time of `downloadUrl` in ISO 8601 format. After expiration, call GET `/v1/reports/{id}` to obtain a fresh URL. example: '2025-01-15T15:00:00Z' Camt053StatementRequest: type: object description: Request body for a CAMT.053 daily statement for a specific date. required: - reportType - date properties: reportType: type: string enum: - camt053 description: Report type identifier. example: camt053 date: type: string description: | The date of the daily CAMT.053 statement to retrieve (YYYY-MM-DD). Must be a past date for which a statement has been generated. format: date example: '2025-01-15' CamtManagedRequest: type: object description: > Request body for a managed CAMT report. Supported for `daily` timeframe only. required: - reportType - timeframe - date properties: reportType: type: string enum: - camt_managed description: Report type identifier. example: camt_managed timeframe: type: string enum: - daily description: | Reporting period granularity. - `daily`: the report covers the single day given by `date`. example: daily date: type: string format: date description: > Date covered by the report (YYYY-MM-DD format). Must be a past date with a generated report. example: '2026-05-20' clientEntityId: type: string format: uuid nullable: true description: > Optional client entity identifier for multi-tenant lookups. When omitted, the entity is resolved from the authenticated caller. example: 9b2c1f7e-4d3a-4f8b-bc2a-1e0d5a6c7b88 ManagedPayoutTransactionsRequest: type: object description: > Request body for a managed payout transactions report. Supported for both `daily` and `monthly` timeframes. required: - reportType - timeframe - date properties: reportType: type: string enum: - managed_payout_transactions description: Report type identifier. example: managed_payout_transactions timeframe: type: string enum: - daily - monthly description: > Reporting period granularity. - `daily`: the report covers the single day given by `date` (`YYYY-MM-DD`). - `monthly`: the report covers the calendar month given by `date` (`YYYY-MM`). example: daily date: type: string description: > The period the report covers. The format depends on `timeframe`: daily reports use `YYYY-MM-DD`, and monthly reports use `YYYY-MM`. Passing a full date for a monthly report returns a `400`. Must be a past period for which a report has been generated. example: '2026-05-20' clientEntityId: type: string format: uuid nullable: true description: > Optional client entity identifier for multi-tenant lookups. When omitted, the entity is resolved from the authenticated caller. example: 9b2c1f7e-4d3a-4f8b-bc2a-1e0d5a6c7b88 ManagedPaymentWalletBalancesRequest: type: object description: > Request body for a managed payment wallet balances report. Only the `daily` timeframe is supported; `monthly` is rejected with a `400`. required: - reportType - timeframe - date properties: reportType: type: string enum: - managed_payment_wallet_balances description: Report type identifier. example: managed_payment_wallet_balances timeframe: type: string enum: - daily description: > Reporting period granularity. Only `daily` is supported for this report type; `monthly` is rejected with a `400`. example: daily date: type: string format: date description: > The report date (YYYY-MM-DD). Must be a past date for which a report has been generated. example: '2026-05-20' clientEntityId: type: string format: uuid nullable: true description: > Optional client entity identifier for multi-tenant lookups. When omitted, the entity is resolved from the authenticated caller. example: 9b2c1f7e-4d3a-4f8b-bc2a-1e0d5a6c7b88 ManagedPayinTransactionsRequest: type: object description: > Request body for a managed payin transactions report. Supported for both `daily` and `monthly` timeframes. required: - reportType - timeframe - date properties: reportType: type: string enum: - managed_payin_transactions description: Report type identifier. example: managed_payin_transactions timeframe: type: string enum: - daily - monthly description: > Reporting period granularity. - `daily`: the report covers the single day given by `date` (`YYYY-MM-DD`). - `monthly`: the report covers the calendar month given by `date` (`YYYY-MM`). example: daily date: type: string description: > The period the report covers. The format depends on `timeframe`: daily reports use `YYYY-MM-DD`, and monthly reports use `YYYY-MM`. Passing a full date for a monthly report returns a `400`. Must be a past period for which a report has been generated. example: '2026-05-20' clientEntityId: type: string format: uuid nullable: true description: > Optional client entity identifier for multi-tenant lookups. When omitted, the entity is resolved from the authenticated caller. example: 9b2c1f7e-4d3a-4f8b-bc2a-1e0d5a6c7b88 headers: XRequestId: description: >- Universally unique identifier (UUID v4) for the request. Helpful for identifying a request when communicating with Circle support. schema: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde 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: type: object title: BadRequest required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 400 message: Bad request. examples: response: value: code: 400 message: Bad request. 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: type: object title: NotAuthorized required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 401 message: Malformed authorization. examples: response: value: code: 401 message: Malformed authorization. Forbidden: description: >- The request provides authentication, but the authenticated user does not possess sufficient permissions for accessing this resource. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: type: object title: Forbidden required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 3 message: Forbidden examples: response: value: code: 3 message: Forbidden NotFound: description: The specified resource was not found. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: type: object title: NotFound required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 404 message: Not found. examples: response: value: code: 404 message: Not found. InternalServerError: description: Unexpected server error. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: type: object title: InternalServerError required: - code - message properties: code: type: integer example: 400 message: type: string example: Something went wrong. example: code: 500 message: Internal server error. examples: response: value: code: 500 message: Internal server error. securitySchemes: bearerAuth: type: http scheme: bearer ````