> ## 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. # 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. Alternative billing models are available by exception. Contact Circle to arrange one outside the API. ## 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)