bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 73쪽
as an onramp) is the process of depositing fiat currency and
receiving an equivalent amount of stablecoins. When you send a fiat transfer to
Circle, Circle credits your Mint account balance with the corresponding
stablecoin amount at a 1:1 ratio.
The minting flow works as follows:
1. You initiate a fiat transfer from your linked bank account to Circle.
2. Circle receives the fiat deposit and credits your Mint account balance.
3. The stablecoins become available for onchain transfers or other operations.
Circle supports multiple payment rails for fiat deposits, including standard
wires (FedWire and SWIFT), real-time interbank rails (RTP, SPEI, SEPA, and
CHATS) in supported regions, and book transfers when you bank with one of
Circle's settlement partners. Rail availability depends on your region and the
currency you are depositing.
**Settlement timing:** Domestic wire deposits received before the daily cutoff
settle on the same business day. Real-time interbank rails settle in seconds,
subject to network operating hours and transaction limits. International wires
take 1-3 business days depending on intermediary banks. In the sandbox
environment, mock wire deposits process in batches and may take up to 15
minutes.
For step-by-step instructions, see
[Deposit Fiat](/circle-mint/howtos/deposit-fiat).
## Redemption
Redemption (also known as an offramp) is the reverse of minting. You convert
stablecoins back to fiat currency by creating a payout to a linked bank account.
The redemption flow works as follows:
1. You create a payout request specifying the amount and destination bank
account.
2. Circle debits the stablecoin amount from your Mint account balance.
3. Circle sends a fiat transfer to your bank account using the appropriate rail
for your region and bank.
**Settlement timing:** Payouts typically settle on the next business day. In
some cases, your bank may reject the incoming wire, resulting in a returned
withdrawal. If a payout is returned, the funds are credited back to your Mint
account balance.
For step-by-step instructions, see
[Withdraw Fiat](/circle-mint/howtos/withdraw-fiat).
## Account structure
Your Circle Mint account has several key components that work together to
support minting, redemption, and onchain transfers.
### Primary wallet
Every Circle Mint account has a primary wallet identified by a `masterWalletId`.
You retrieve this identifier from the `/v1/configuration` endpoint. The primary
wallet serves as the source for outbound transfers and the destination for
inbound deposits.
### Balances
Your account maintains two types of balances:
* **Available balance:** Settled funds you can transfer or redeem immediately.
* **Unsettled balance:** Funds that are in transit and not yet available. Wire
deposits appear as unsettled until they clear.
### Linked bank accounts
You register external bank accounts to send and receive fiat. Each linked bank
account receives a unique Virtual Account Number (VAN). When you wire funds to
Circle using the VAN, Circle attributes the deposit to your account without
requiring a tracking reference in the payment instruction.
### Deposit addresses
Circle generates one deposit address per blockchain for your account. These
addresses receive inbound stablecoin transfers from external wallets. You
retrieve your deposit addresses through the API for each
[supported blockchain](/circle-mint/references/supported-chains-and-currencies).
### Recipient addresses
Recipient addresses are external blockchain addresses that you register and
allowlist for outbound transfers. You must create a recipient address before you
can send stablecoins to it. This allowlisting step provides an additional layer
of security for outbound transfers.
## Onchain transfers
Circle Mint supports both receiving and sending stablecoins onchain.
* **Receiving:** External wallets send USDC or EURC to your deposit address on
any supported blockchain. Circle detects the transfer and credits your account
after the required number of
[blockchain confirmations](/circle-mint/references/blockchain-confirmations).
* **Sending:** You create a transfer to a registered recipient address. Circle
debits your balance and broadcasts the transaction onchain.
### Transfer status lifecycle
Onchain transfers progress through the following statuses:
| Status | Description |
| - | - |
| `pending` | The transfer request is created but not yet broadcast onchain. |
| `running` | The transaction is broadcast and awaiting blockchain confirmations. |
| `complete` | The required confirmations are reached and the transfer is final. |
For details on confirmation requirements per blockchain, see
[Blockchain confirmations](/circle-mint/references/blockchain-confirmations).
For step-by-step transfer instructions, see
[Transfer USDC Onchain](/circle-mint/howtos/transfer-on-chain).
## Network fees
Circle covers gas fees for outbound stablecoin transfers in most cases. You do
not need to hold the native token of each blockchain to send USDC or EURC from
your Mint account.
## Travel Rule compliance
Transfers of \$3,000 or more in value on supported blockchains are subject to the
FinCEN Travel Rule, which requires identity data about the originator of the
transaction.
How Circle handles the identity requirement depends on the type of transfer:
* **Business account transfers:** Circle uses your company's identity stored on
file. You do not need to include identity data in each request.
* **Third-party payouts:** If you send funds on behalf of someone else, you must
provide the originator's identity (name and address) in the payout request.
Omitting required identity data causes the transfer to fail.
For the full list of supported blockchains and implementation details, see
[Travel Rule compliance](/circle-mint/howtos/transfer-on-chain#travel-rule-compliance).
## Approval workflows
Customers in France and Singapore are subject to additional recipient address
verification requirements. Before an outbound transfer can proceed, the
recipient address must be verified through the
[Mint Console](https://app.circle.com/signin). This approval step ensures
compliance with local regulatory requirements in those jurisdictions.
# Institutional API
Source: https://developers.circle.com/circle-mint/concepts/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)
# How-to: Add collateral to a loan
Source: https://developers.circle.com/circle-mint/howtos/add-collateral
Post additional cirBTC as collateral to an open loan to lower its LTV and restore its health factor after a margin call.
Post additional cirBTC as collateral against an open loan. Adding collateral
lowers the loan's
[LTV](/circle-mint/concepts/digital-asset-backed-borrowing#ltv-health-factor-and-liquidation)
and raises its health factor without changing the outstanding debt. This is the
standard response to a margin call when you want to keep the loan open rather
than repay it.
## Prerequisites
Before you begin, ensure that you've:
* Completed the
[Borrow USDC against cirBTC collateral](/circle-mint/quickstarts/borrow-with-cirbtc)
quickstart and hold at least one loan in `active` status.
* Held sufficient cirBTC in your Mint balance to cover the additional collateral
you plan to post.
## Steps
<Steps>
<Step title="Submit the collateral request">
Call
[`POST /v1/borrow/loans/{id}/collateral`](/api-reference/circle-mint/digital-asset-backed-borrowing/add-borrow-loan-collateral)
with the amount of cirBTC you want to add in raw `uint256` base units.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/borrow/loans/fc988ed5-c129-4f70-a064-e5beb7eb8e32/collateral \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "e5c6d7b8-9012-4a3b-cdef-1234567890ab",
"amount": "2500000"
}'
```
The endpoint returns an `onchainJob` with `jobType: add_collateral`:
```json theme={null}
{
"data": {
"id": "f6a7b8c9-d012-3456-efab-456789012345",
"jobType": "add_collateral",
"status": "received",
"createDate": "2026-06-25T10:15:00.000Z",
"updateDate": "2026-06-25T10:15:00.000Z"
}
}
```
Save the job `id`. You poll it in the next step.
</Step>
<Step title="Poll the job to completion">
Circle builds, signs, and submits the onchain UserOperation for the added
collateral. The job progresses through `submitted` and `confirmed` to
`completed`. Poll
[`GET /v1/borrow/jobs/{id}`](/api-reference/circle-mint/digital-asset-backed-borrowing/get-borrow-job)
until you see the terminal state.
```json theme={null}
{
"data": {
"id": "f6a7b8c9-d012-3456-efab-456789012345",
"jobType": "add_collateral",
"status": "completed",
"amount": "0.025",
"asset": "CIRBTC",
"collateralAmount": "0.025",
"collateralAsset": "CIRBTC",
"loanId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
"txHash": "0x3c4d5e6f70819293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9aabb",
"createDate": "2026-06-25T10:15:00.000Z",
"updateDate": "2026-06-25T10:17:00.000Z"
}
}
```
</Step>
<Step title="Confirm the updated position">
Fetch the loan to confirm the added collateral is reflected and the health
factor has improved:
```bash theme={null}
curl https://api-sandbox.circle.com/v1/borrow/loans/fc988ed5-c129-4f70-a064-e5beb7eb8e32 \
-H "Authorization: Bearer $API_KEY"
```
`collateralAmount` on the loan should now include the added amount, and
`healthFactor` should be higher than it was before.
</Step>
</Steps>
# How-to: Add another wallet owner
Source: https://developers.circle.com/circle-mint/howtos/add-wallet-owner
Register an additional passkey as an authorized owner on your MSCA to extend recovery coverage across additional devices.
Register an additional
[WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)
passkey as an owner on your
[modular smart contract account (MSCA)](/wallets/account-types#smart-contract-accounts-sca-and-msca).
Additional owners serve as recovery keys. They extend recovery coverage across
additional devices without changing how routine signing works. See
[How Digital Asset-Backed Borrowing works](/circle-mint/concepts/digital-asset-backed-borrowing)
for the wallet architecture.
## Prerequisites
Before you begin, ensure that you've:
* Completed the
[Borrow USDC against cirBTC collateral](/circle-mint/quickstarts/borrow-with-cirbtc)
quickstart and provisioned a wallet.
* Registered a new WebAuthn passkey on the device you want to add as an owner.
Capture the P-256 public key and the WebAuthn credential identifier as hex
strings.
## Steps
<Steps>
<Step title="Submit the add-owner request">
Call
[`POST /v1/borrow/wallets/owners`](/api-reference/circle-mint/digital-asset-backed-borrowing/add-borrow-wallet-owner)
with the new passkey's public key and credential ID.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/borrow/wallets/owners \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "f7a8b9c0-d123-4e56-7890-abcdef123456",
"ownerKey": "0x04c1d2e3f4051627384950a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6",
"credentialId": "b2c3d4e5f6071829"
}'
```
The endpoint returns an `onchainJob` with `jobType: add_owner`:
```json theme={null}
{
"data": {
"id": "a7b8c9d0-e123-4567-890a-bcdef1234567",
"jobType": "add_owner",
"status": "received",
"createDate": "2026-06-25T11:00:00.000Z",
"updateDate": "2026-06-25T11:00:00.000Z"
}
}
```
Save the job `id`. You poll it in the next step.
</Step>
<Step title="Wait for the operation to complete">
Poll
[`GET /v1/borrow/jobs/{id}`](/api-reference/circle-mint/digital-asset-backed-borrowing/get-borrow-job)
until `status` reaches `completed`.
```json theme={null}
{
"data": {
"id": "a7b8c9d0-e123-4567-890a-bcdef1234567",
"jobType": "add_owner",
"status": "completed",
"txHash": "0x4d5e6f70819293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9aabbccdd",
"createDate": "2026-06-25T11:00:00.000Z",
"updateDate": "2026-06-25T11:01:30.000Z"
}
}
```
</Step>
<Step title="Confirm the new owner">
Fetch the wallet and confirm the new owner appears in the `owners` array with
`status: active`:
```bash theme={null}
curl https://api-sandbox.circle.com/v1/borrow/wallets \
-H "Authorization: Bearer $API_KEY"
```
```json theme={null}
{
"data": [
{
"id": "9c1b2a3d-4e5f-6071-8293-a4b5c6d7e8f9",
"walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f9f68C",
"owners": [
{
"id": "1f2e3d4c-5b6a-7980-1234-56789abcdef0",
"ownerType": "passkey",
"publicKey": "0x04b0a1c2d3e4f5061728394a5프로젝트로 돌아가기
