bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 75쪽
ases the loan's cirBTC collateral back to your Mint balance and the
loan transitions to `closed`.
* **Partial repay**: set `mode: PARTIAL` and include the `amount` you want to
apply in raw `uint256` base units. The loan stays `active` with a reduced
debt. No collateral is released.
<Tabs>
<Tab title="Full repay">
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/borrow/loans/fc988ed5-c129-4f70-a064-e5beb7eb8e32/repayments \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "d7a3e2c1-8f45-4b91-ae67-2c9d0f8b3e5a",
"mode": "FULL"
}'
```
</Tab>
<Tab title="Partial repay">
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/borrow/loans/fc988ed5-c129-4f70-a064-e5beb7eb8e32/repayments \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "d7a3e2c1-8f45-4b91-ae67-2c9d0f8b3e5a",
"mode": "PARTIAL",
"amount": "50000000000"
}'
```
</Tab>
</Tabs>
The endpoint returns an `onchainJob` with `jobType: repay`:
```json theme={null}
{
"data": {
"id": "e5f6a7b8-9012-3456-efab-345678901234",
"jobType": "repay",
"status": "received",
"createDate": "2026-06-25T10:00:00.000Z",
"updateDate": "2026-06-25T10:00: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 repayment.
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": "e5f6a7b8-9012-3456-efab-345678901234",
"jobType": "repay",
"status": "completed",
"amount": "500.00",
"asset": "USD",
"loanId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
"txHash": "0x2b3c4d5e6f70819293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9aa",
"createDate": "2026-06-25T10:00:00.000Z",
"updateDate": "2026-06-25T10:02:00.000Z"
}
}
```
</Step>
<Step title="Confirm the outcome">
Fetch the loan to inspect the updated position:
```bash theme={null}
curl https://api-sandbox.circle.com/v1/borrow/loans/fc988ed5-c129-4f70-a064-e5beb7eb8e32 \
-H "Authorization: Bearer $API_KEY"
```
For a full repay, the loan's `status` is `closed` and `debtAmount` is zero. The
cirBTC collateral is credited back to your Mint balance. Confirm the credit by
calling `GET /v1/businessAccount/balances`.
For a partial repay, the loan's `status` remains `active` and `debtAmount`
reflects the reduced outstanding balance. No collateral change occurs.
</Step>
</Steps>
# How-to: Transfer USDC onchain
Source: https://developers.circle.com/circle-mint/howtos/transfer-on-chain
Receive USDC and EURC via deposit addresses and send them to external blockchain wallets using the Circle Mint API.
Receive USDC or EURC by generating deposit addresses for external wallets to
send to, or send USDC or EURC to allowlisted recipient addresses on supported
blockchains. Third-party payouts may require Travel Rule compliance data; see
[Travel rule compliance](/circle-mint/references/travel-rule-compliance) for
thresholds, schemas, and failure modes.
## Prerequisites
Before you begin:
* Complete the
[account and API key setup](/circle-mint/quickstarts/getting-started).
* Review
[supported chains and currencies](/circle-mint/references/supported-chains-and-currencies)
for available blockchains.
* (For sending) Have a funded Circle Mint account.
* (For sending) All recipient addresses must be approved by an account
administrator through the [Mint Console](https://app.circle.com/signin) before
you can create transfers. If your account is domiciled in France or Singapore,
addresses require additional verification through the Mint Console.
## Step 1. Receive USDC via deposit address
### Step 1.1. Create a deposit address
Use the create deposit address endpoint to generate an address for receiving
USDC or EURC on a specific blockchain.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/deposit \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "currency": "USD", "chain": "ARC"}'
```
Expected response:
```json theme={null}
{
"data": {
"id": "d51d72d2-9955-4340-b3fd-2f07a82a1e6c",
"address": "0xbd01242af414961c25aa72dcae06646fc52e9b92",
"currency": "USD",
"chain": "ARC"
}
}
```
<Note>
You can create one deposit address per blockchain. Use the same address for
all deposits on that blockchain.
</Note>
### Step 1.2. Send funds to your deposit address
This step happens outside the Circle Mint API. The sender transfers USDC or EURC
from their external wallet to your deposit address on the matching blockchain.
<Warning>
Sending funds on the wrong blockchain results in permanent loss. Always
confirm the blockchain network matches between the sender's wallet and your
deposit address.
</Warning>
### Step 1.3. Verify the deposit
Use the
[list transfers](/api-reference/circle-mint/account/list-business-transfers)
endpoint to confirm the incoming transfer has settled.
```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/transfers \
-H "Authorization: Bearer ${YOUR_API_KEY}"
```
Expected response:
```json theme={null}
{
"data": [
{
"id": "a6a1b575-13d5-4e73-9da7-73e2a3e4418a",
"source": {
"type": "blockchain",
"chain": "ARC"
},
"destination": {
"type": "wallet",
"id": "1000066041"
},
"amount": {
"amount": "100.00",
"currency": "USD"
},
"transactionHash": "0x4cfd25b5ab46e9fe25e845e7a7e0ea2f1f7e4bba3c6e0f1db0b846e4a1bc5fd2",
"status": "complete",
"createDate": "2024-01-01T12:00:00.000Z"
}
]
}
```
The transfer reaches `complete` status after the required number of
[blockchain confirmations](/circle-mint/references/blockchain-confirmations) for
the deposit's blockchain.
## Step 2. Send USDC to an external address
### Step 2.1. Add a recipient address
Use the create recipient address endpoint to allowlist an external blockchain
address for outbound transfers.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/wallets/addresses/recipient \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"idempotencyKey": "2a308497-e66e-4c42-ac1e-7bedab86d958", "address": "0x493A9869E3B5f846f72267ab19B76e9bf99d51b1", "chain": "ARC", "currency": "USD", "description": "Treasury wallet"}'
```
Expected response:
```json theme={null}
{
"data": {
"id": "cfa01bb0-d166-5506-a48a-56f2beab559f",
"address": "0x493a9869e3b5f846f72267ab19b76e9bf99d51b1",
"chain": "ARC",
"currency": "USD",
"description": "Treasury wallet"
}
}
```
Adding a recipient address through the API creates a pending request. An account
administrator must approve the address through the
[Mint Console](https://app.circle.com/signin) before you can send transfers to
it. A confirmation notification is sent to all administrators.
### Step 2.2. Create a transfer
Use the create transfer endpoint to send funds to the approved recipient
address.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/transfers \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"idempotencyKey": "6ec3827d-15bb-442e-9d4c-32e73e61cbf4", "destination": {"type": "verified_blockchain", "addressId": "cfa01bb0-d166-5506-a48a-56f2beab559f"}, "amount": {"currency": "USD", "amount": "25.00"}}'
```
Expected response:
```json theme={null}
{
"data": {
"id": "21fd4ec4-bad1-4eb2-9fc5-60320dedc7ea",
"source": {
"type": "wallet",
"id": "1016875042"
},
"destination": {
"type": "blockchain",
"address": "0x493a9869e3b5f846f72267ab19b76e9bf99d51b1",
"chain": "ARC"
},
"amount": {
"amount": "25.00",
"currency": "USD"
},
"status": "pending",
"createDate": "2024-07-15T16:41:12.395Z"
}
}
```
### Step 2.3. Check the transfer status
Use the get transfer endpoint to monitor the status of your transfer.
```bash theme={null}
curl -X GET https://api-sandbox.circle.com/v1/businessAccount/transfers/21fd4ec4-bad1-4eb2-9fc5-60320dedc7ea \
-H "Authorization: Bearer ${YOUR_API_KEY}"
```
The transfer progresses through these statuses:
* **`pending`**: Circle received the request.
* **`running`**: The transaction is broadcast onchain. The response includes a
`transactionHash`.
* **`complete`**: Blockchain finality reached -- the required number of
confirmations passed.
Expected response for a running transfer:
```json theme={null}
{
"data": {
"id": "21fd4ec4-bad1-4eb2-9fc5-60320dedc7ea",
"source": {
"type": "wallet",
"id": "1016875042"
},
"destination": {
"type": "blockchain",
"address": "0x493a9869e3b5f846f72267ab19b76e9bf99d51b1",
"chain": "ARC"
},
"amount": {
"amount": "25.00",
"currency": "USD"
},
"transactionHash": "0x0654eee4f609f9c35e376cef9455dd9fc1546c482c5c32c8f8d434ead14fcf97",
"status": "running",
"createDate": "2024-07-15T16:41:12.395Z"
}
}
```
## See also
* [How minting and redemption works](/circle-mint/concepts/how-minting-works):
understand the transfer lifecycle
* [Travel rule compliance](/circle-mint/references/travel-rule-compliance):
thresholds, schemas, and failure modes for third-party payouts
* [Blockchain confirmations](/circle-mint/references/blockchain-confirmations):
confirmation counts by blockchain
* [Supported Chains and Currencies](/circle-mint/references/supported-chains-and-currencies):
available blockchains
# How-to: Withdraw fiat
Source: https://developers.circle.com/circle-mint/howtos/withdraw-fiat
Redeem USDC or EURC to fiat and withdraw funds to your bank account using the Circle Mint API.
Redeem (offramp) USDC or EURC in your Circle Mint balance to fiat and send funds
to a linked bank account. You can track payout status from `pending` through
`complete` or `failed`, and handle returned withdrawals caused by bank-side
rejections. Payouts route through the `/wires` endpoint and support standard
wires, real-time interbank rails (RTP, SPEI, SEPA, CHATS) where available, and
book transfers when applicable -- Circle selects the rail based on your
destination bank and region.
## Prerequisites
Before you begin:
* Complete the
[account and API key setup](/circle-mint/quickstarts/getting-started).
* Have a funded Circle Mint account with available USDC or EURC balance.
* Have a linked bank account. If you have not linked one, see
[Deposit Fiat](/circle-mint/howtos/deposit-fiat) Step 1.
* If your Circle Mint account is domiciled in Singapore or France, verify your
payout recipients through the [Mint Console](https://app.circle.com/signin)
before proceeding. Unverified recipients cause payouts to remain in `pending`
status.
## Step 1. Verify your balance
Before you initiate a withdrawal, confirm that your available balance covers the
amount you plan to send.
```bash theme={null}
curl -X GET https://api-sandbox.circle.com/v1/businessAccount/balances \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H "Content-Type: application/json"
```
Expected response:
```json theme={null}
{
"data": {
"available": [
{
"amount": "150.00",
"currency": "USD"
}
],
"unsettled": [
{
"amount": "25.00",
"currency": "USD"
}
]
}
}
```
The `available` array shows funds you can withdraw immediately. The `unsettled`
array shows funds that are still being processed and are not yet available.
## Step 2. Create a payout
Use the
[create a payout](/api-reference/circle-mint/account/create-business-payout)
endpoint to send funds from your Circle Mint account to your linked bank
account.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/payouts \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"idempotencyKey": "'$(uuidgen)'", "destination": {"type": "wire", "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636"}, "amount": {"currency": "USD", "amount": "75.00"}}'
```
Replace the `destination.id` value with the bank account ID returned when you
linked your bank account.
Expected response:
```json theme={null}
{
"data": {
"id": "9cf38c76-cac4-40d8-a516-f46e9a610a85",
"amount": {
"amount": "75.00",
"currency": "USD"
},
"status": "pending",
"sourceWalletId": "1016875042",
"destination": {
"type": "wire",
"id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
"name": "WELLS FARGO BANK, NA ****0010"
},
"createDate": "2024-01-15T14:22:31.062Z",
"updateDate": "2024-01-15T14:22:31.062Z"
}
}
```
Record the `id` from the response to check the payout status in the next step.
## Step 3. Check the payout status
Use the [get a payout](/api-reference/circle-mint/account/get-business-payout)
endpoint to check the current status of your withdrawal.
```bash theme={null}
curl -X GET https://api-sandbox.circle.com/v1/businessAccount/payouts/9cf38c76-cac4-40d8-a516-f46e9a610a85 \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H "Content-Type: application/json"
```
A payout moves through the following statuses:
* **`pending`**: Circle has received the payout request and is processing it.
* **`complete`**: Funds have been sent to the receiving bank.
* **`failed`**: The payout could not be processed. Check the `errorCode` field
for details.
Expected response for a completed payout:
```json theme={null}
{
"data": {
"id": "9cf38c76-cac4-40d8-a516-f46e9a610a85",
"amount": {
"amount": "75.00",
"currency": "USD"
},
"status": "complete",
"sourceWalletId": "1016875042",
"destination": {
"type": "wire",
"id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
"name": "WELLS FARGO BANK, NA ****0010"
},
"createDate": "2024-01-15T14:22:31.062Z",
"updateDate": "2024-01-16T09:15:42.778Z"
}
}
```
Payouts are asynchronous. To track status changes without polling, subscribe to
`payouts` webhook notifications. Alternatively, poll the get a payout endpoint
at a reasonable interval until the status reaches `complete` or `failed`.
### Returned withdrawals
Even after a payout reaches `complete` status, bank-side issues can cause the
wire to be returned. Common reasons include:
* Incorrect account details, such as a wrong routing number or a closed account.
* Compliance holds at the receiving bank.
* Beneficiary name mismatch between the payout and the bank account on file.
When a wire is returned, the funds are re-credited to your Circle Mint balance.
Monitor webhook notifications for `payouts` events to detect returns. If a
payout fails or is returned, verify the bank account details and retry with a
new idempotency key.
## See also
* [How minting and redemption works](/circle-mint/concepts/how-minting-works) --
understand the redemption process
* [Sandbox to Production](/circle-mint/references/sandbox-and-testing) --
production settlement timing differences
* [Create a payout](/api-reference/circle-mint/account/create-business-payout)
\-- API reference
# How mTLS authentication works
Source: https://developers.circle.com/circle-mint/mtls-authentication
Learn how mutual TLS authentication adds a transport-layer certificate check to Circle Mint API access, as a MiCA requirement or an optional security enhancement.
Mutual Transport Layer Security (mTLS) adds transport-layer certificate
authentication on top of your existing API key. With mTLS enabled, both Circle
and your client verify each other's identity before any API request is
processed. A request is accepted only when it arrives over a connection that
both sides have authenticated.
## Who should use mTLS
You can enable mTLS in either of two situations:
* **As a MiCA requirement.** Entities operating in an EU/EEA member state under
the Markets in Crypto-Assets (MiCA) regulation must use mTLS on regulated API
endpoints.
* **As an optional security enhancement.** Any Circle Mint customer with an
active API key can opt in to mTLS for an additional layer of transport-level
authentication. Opting in is voluntary, and there's no regulatory
prerequisite.
The certificate model, setup flow, and API key lifecycle are the same in both
cases. Only two things differ, depending on why you enable mTLS:
| Aspect | MiCA-regulated | Optional (non-MiCA) |
| - | - | - |
| API hostname | Regional EU hostname `api-eu.circle.com` | Standard hostname `api.circle.com` (unchanged) |
| Server certificate you validate | A Qualified Website Authentication Certificate (QWAC), validated for PSD2 | Circle's standard server certificate, validated as usual |
## What is mTLS
Standard TLS (one-way TLS) authenticates only the server. Your client verifies
Circle's certificate during the TLS handshake, but Circle has no way to verify
your client's identity at the transport layer.
Mutual TLS (mTLS) extends this model so that both sides present certificates:
* **Server authentication**: Circle presents its certificate to your client,
just as in standard TLS.
* **Client authentication**: Your client presents a client certificate issued by
Circle's private certificate authority (CA) during the same handshake. Circle
validates that certificate against its private CA before accepting the
connection.
The result is a two-way trust relationship established before any HTTP traffic
flows. Only after both certificates are validated does the connection proceed to
the application layer, where your API key is checked as usual.
```mermaid theme={null}
sequenceDiagram
participant C as Your client
participant S as Circle API
Note over C,S: TLS handshake begins
S->>C: Presents server certificate
C->>C: Validates server certificate
C->>S: Presents client certificate (issued by Circle's private CA)
S->>S: Validates client certificate against its private CA
Note over C,S: TLS handshake complete
Note over C,S: Application layer
C->>S: Sends API request with Bearer token
S->>S: Validates API key
S-->>C: Returns API response
```
## Client certificates
Circle issues your client certificate from its private certificate authority
(CA), managed through AWS Private CA. You do not purchase a Qualified Website
Authentication Certificate (QWAC) or any other certificate from a third party.
The issuance flow keeps your private key in your own environment:
<Steps>
<Step title="Generate a key pair and CSR locally">
You generate an Elliptic Curve Digital Signature Algorithm (ECDSA) P-256 key
pair and a PKCS#10 certificate signing request (CSR) locally. Circle accepts
only ECDSA P-256 keys; RSA keys and other curves are rejected.
</Step>
<Step title="Submit the CSR to Circle">
You submit the CSR, which contains only your public key, to Circle. Your
private key never leaves your environment.
</Step>
<Step title="Receive your signed certificate">
Circle validates the CSR, issues a signed client certificate from its
private CA, and returns a single file, `client-fullchain.pem`, through a
secure, out-of-band channel. It contains your signed certificate followed by
the CA certificate chain.
</Step>
</Steps>
Circle assigns the certificate fields, including the subject name, key usage
(`digitalSignature`), and extended key usage (`clientAuth`). The certificate is
valid for 365 days from the date of issuance.
### Certificate validation
Because Circle issues your client certificate from its own private CA, Circle
validates the certificate you present against that CA on every request. You do
not pre-register the certificate separately; presenting it during the TLS
handshake is sufficient. If the certificate is expired or does not chain to
Circle's private CA, requests fail at the transport layer before the API key is
evaluated.
For step-by-step instructions on generating a key pair and CSR and obtaining
your certificate, see
[How-to: Set up mTLS authentication](/circle-mint/set-up-mtls-authentication).
### Server certificate v프로젝트로 돌아가기
