> ## 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.

# Document file rules

> Filename characters, size limits, accepted types, and upload error codes for End User Onboarding

Before storing a document, the
[Upload a document for an application](https://developers.circle.com/api-reference/circle-mint/onboarding/upload-document#upload-a-document-for-an-application)
endpoint validates the filename and file bytes. A failed check returns `400`
with an `errors` array that names the failing field and error code.

For upload steps, see
[Upload documents](/end-user-onboarding/howtos/upload-documents).

## Read limits from the schema

Each file field can set its own types and size. Retrieve the application schema
(`GET /v1/onboarding/partner/applications/{applicationId}/schema`) and read
`x-fileUpload` on the target field:

```json theme={null}
"genericFileUploadBusinessRegistration": {
  "x-fileUpload": {
    "acceptedTypes": ["application/pdf", "image/jpeg", "image/png"],
    "maxSizeMb": 10
  }
}
```

If `x-fileUpload` is absent, the API uses the defaults in the following tables.

## Filename

The API strips `/` and `\` from `fileName`, then trims spaces at each end.

| Rule | Value |
| - | - |
| Length | 1 to 255 characters after path components are removed |
| Characters | Letters, numbers, spaces, hyphens (`-`), underscores (`_`), dots (`.`), commas (`,`), and parentheses (`()`) |
| Example | `Ownership Chart (1).pdf`, `Company, LLC.pdf` |

Quotes, slashes, and other punctuation fail the character check.

## File type

The API reads magic bytes in `fileContent`. It doesn't trust the `Content-Type`
header.

Known signatures are PDF, JPEG, PNG, ZIP (Office Open XML), and OLE2 (legacy
Office). A file with no matching signature returns `unrecognized_type`.

| Source | Accepted types |
| - | - |
| Field `x-fileUpload.acceptedTypes` | The types listed on that field |
| No `x-fileUpload` | `application/pdf`, `image/jpeg`, `image/png` |

Office files (DOC, XLS, DOCX, XLSX) pass only when the field schema lists those
types. The default list doesn't include them.

## File size

| Source | Limit |
| - | - |
| Field `x-fileUpload.maxSizeMb` | That value in megabytes |
| No `x-fileUpload` | 10 MB |

A file over the limit returns `too_large`.

## Error codes

A failed check returns HTTP `400` with numeric code `181102`. The body includes
`errors` with `field` and `code`.

| `field` | `code` | When |
| - | - | - |
| `fileName` | `required` | `fileName` is missing or blank |
| `fileName` | `too_long` | Name is longer than 255 characters |
| `fileName` | `invalid` | Name is empty after path components are removed |
| `fileName` | `invalid_characters` | Name has a character outside the allowlist |
| `fileContent` | `required` | `fileContent` is missing |
| `fileContent` | `empty` | File has zero bytes |
| `fileContent` | `unrecognized_type` | File bytes don't match a known type |
| `fileContent` | `not_accepted` | Type isn't in the field's `x-fileUpload.acceptedTypes` |
| `fileContent` | `too_large` | File is larger than `x-fileUpload.maxSizeMb` (default 10 MB) |