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

# Institutional API

> Understand how the Institutional API lets Circle Mint distributors mint, redeem, and transfer on behalf of compliance-screened external entities with their own per-entity wallets.

The Institutional API is for Circle Mint customers with the institutional
entitlement (Distributors) who operate fiat-to-stablecoin flows on behalf of
their own institutional end clients. It lets you onboard those end clients as
external entities, screen them through Circle compliance, and then mint, redeem,
and transfer USDC on their behalf. Each entity gets its own dedicated wallet so
balances and money movement stay segregated by counterparty.

## Why use the Institutional API

Without the Institutional API, every counterparty that needs to mint or redeem
through Circle would have to onboard as a direct Circle Mint customer. The
Institutional API solves that by letting one Distributor's Mint account act as
the integration surface for many institutional end clients. Circle still runs
compliance on each external entity, but the Distributor—not the end client—
holds the API key and runs the integration.

The API is intended for B2B2B Distributors servicing institutional end clients,
such as:

* Commercial banks
* Institutional banks
* Centralized exchanges
* Custodians
* TradFi trading platforms
* Real-world asset (RWA) platforms

Retail-only use cases and internal-only flows do not require the Institutional
API.

## Distributor and external entity

The Institutional API revolves around two roles. The Distributor is the Circle
Mint customer; the external entity is the Distributor's institutional end
client. Each role has a different relationship to Circle and to the API.

| Aspect | Distributor | External entity |
| - | - | - |
| Role | The Circle Mint customer integrating the Institutional API. | The Distributor's institutional end client. |
| API access | Holds the API key and authenticates all requests. | Never accesses the Circle Mint API directly. |
| Wallet | Owns a primary wallet identified by `masterWalletId`, used as the default source and destination when no entity wallet is specified. | Receives a dedicated subaccount wallet (type `end_user_wallet`) after Circle accepts the entity in compliance. |
| Identity | Calls [`POST /v1/externalEntities`](/api-reference/circle-mint/institutional/create-external-entity) to onboard each external entity. | Identified by `businessName`, `businessUniqueIdentifier` (tax ID), `identifierIssuingCountryCode`, and `address` submitted by the Distributor. |
| Money movement | Initiates mints, redemptions, and onchain transfers on behalf of each accepted entity. | Funds flow through the entity's `walletId`; the entity itself does not call Circle APIs. |

## Compliance lifecycle

Every call to
[`POST /v1/externalEntities`](/api-reference/circle-mint/institutional/create-external-entity)
triggers a synchronous sanctions screening on the entity's business name, tax ID
(`businessUniqueIdentifier`), issuing country code, and address. The 201
response returns the entity in `complianceState: PENDING` along with the
provisioned `walletId`. The final decision—`ACCEPTED` or `REJECTED`—is delivered
asynchronously through the `externalEntities` webhook topic.

```mermaid theme={null}
sequenceDiagram
    participant D as Distributor
    participant C as Circle
    participant W as Distributor webhook endpoint
    D->>C: POST /v1/externalEntities
    C-->>D: 201 { complianceState: "PENDING" }
    Note over C: Synchronous sanctions screening
    alt Accepted
      C-->>W: externalEntities { complianceState: "ACCEPTED", walletId }
    else Rejected
      C-->>W: externalEntities { complianceState: "REJECTED" }
    end
```

The `walletId` is returned at creation but is unusable while the entity remains
in `PENDING` or `REJECTED`. Wait for the `externalEntities` webhook to deliver
`complianceState: ACCEPTED` before referencing the entity's wallet in any other
endpoint.

## Per-entity wallet model

When Circle accepts an external entity, it provisions a dedicated wallet of type
`end_user_wallet` and surfaces the wallet identifier as `walletId` (for example,
`"212000"`). The wallet is owned by the Distributor's Mint account but
segregated to that entity, so balances and money movement remain attributable
per counterparty.

Every relevant Mint endpoint accepts the entity's `walletId`:

* On `GET` endpoints (such as listing deposits, payouts, or transfers), pass the
  entity wallet as the `walletId` query parameter: `?walletId=212000`.
* On `POST` endpoints (such as creating a payout or an onchain transfer), pass
  the entity wallet in the request body as
  `"source": { "type": "wallet", "id": "212000" }`.

If `walletId` is omitted on a request, Circle defaults to the Distributor's
primary wallet (`masterWalletId`). The primary wallet remains available for the
Distributor's own balances and money movement; the entity wallets sit alongside
it as siblings, not as children of the primary wallet.

## Operational flows

The Institutional API supports three flows on behalf of an accepted external
entity: minting, redeeming, and onchain transfer. The table below summarizes
each flow at a conceptual level. For endpoint-level steps, see
[Manage institutional subaccounts](/circle-mint/quickstarts/manage-institutional-subaccounts).

| Flow | What it does | Where the entity wallet appears |
| - | - | - |
| Mint on behalf of an entity | The end client wires fiat against entity-scoped wire instructions; Circle credits the entity wallet and fires a `deposits` webhook. | `walletId` query parameter on the wire-instructions request. |
| Redeem on behalf of an entity | The Distributor submits a payout from the entity wallet. The Institutional Direct fee is deducted at redemption, so `toAmount` reflects the net amount the entity's bank receives. | `source.id` in the payout request body. |
| Onchain transfer on behalf of an entity | Outbound transfers draw from the entity wallet and target a verified destination from the Distributor's address book; inbound transfers use a per-entity deposit address. | `walletId` query parameter on deposit-address requests; `source.id` in the transfer request body. |

## Billing

Institutional Direct is the default billing model for the Institutional API. A
gross flat fee is applied to every redemption, charged to the end client at the
point of redemption and deducted from the `toAmount` returned on the payout
response. The Distributor sees the net amount in the payout payload, and the
entity's bank receives that net amount.

<Note>
  Alternative billing models are available by exception. Contact Circle to
  arrange one outside the API.
</Note>

## What is not supported

The Institutional API does not support the following operations on behalf of an
external entity:

* Editing or deleting an external entity once it is created. Contact Circle to
  make changes.
* Express routes from entity subaccount wallets.
* Local-currency onramp flows (such as BRL, MXN, or EURC swaps) on behalf of
  entity subaccounts.
* Stablecoin Payins and Stablecoin Payouts against entity wallets.
* Cross-Currency Exchange against entity wallets.
* Credit API operations on behalf of an external entity.

## See also

* [Manage institutional subaccounts](/circle-mint/quickstarts/manage-institutional-subaccounts)
* [Webhook notifications: `externalEntities`](/circle-mint/references/webhook-notifications#externalentities)