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

# Quickstart: Draw an RWA redemption advance with brokerage orders

> Confirm the tokenization flow, find the sell orders for a token burn, and create an RWA Redemption Advance backed by them.

Use an RWA Redemption Advance to draw on a credit line that is connected to a
brokerage provider. A token burn on Arc and the brokerage sell orders for the
underlying shares back the advance. For the conceptual model behind these calls,
see the [Credit API](https://developers.circle.com/circle-mint/concepts/credit-api.md) concept page.

If your RWA Redemption Advance line is not connected to a provider, use the
reserve-then-request flow in
[Reserve and repay a settlement advance](https://developers.circle.com/circle-mint/quickstarts/settlement-advance.md#rwa-redemption-advance)
instead.

## Prerequisites

Before you begin, ensure that you've:

* Contacted your Circle representative to activate RWA Redemption Advance on
  your Circle Mint account and to connect your brokerage provider.
* Confirmed your Circle Mint wallet holds the required USDC `minBalance` for
  your credit line.
* Configured API authentication per
  [Getting Started](https://developers.circle.com/circle-mint/quickstarts/getting-started.md). The following
  examples use `$API_KEY` and the base URL `https://api-sandbox.circle.com`.
* Reviewed the RWA Redemption Advance agreement under the **Agreement** tab in
  the [Mint Console](https://app.circle.com/credit/agreement). Your use of RWA
  Redemption Advance is governed by this agreement.

## Step 1. Check the credit line

Call `GET /v1/credit` to confirm your credit line is active and has sufficient
capacity for the draw.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/credit \
  -H "Authorization: Bearer $API_KEY"
```

Before proceeding, confirm:

* `product` is `rwaRedemptionAdvance`.
* `available.amount` covers the amount you plan to advance.
* `validationErrors` is an empty array.

For the meaning of each field, see the
[credit-line model](https://developers.circle.com/circle-mint/concepts/credit-api.md#the-credit-line-model).

## Step 2. Confirm the tokenization flow

Call `GET /v1/credit/tokenization/providers` to list the providers connected to
your credit line.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/credit/tokenization/providers \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": [{ "provider": "ALPACA", "displayName": "Alpaca" }]
}
```

A provider in the list means your line uses the tokenization flow. Use the
provider in lower case in the paths that follow. An empty list means your line
uses the reserve-then-request flow instead.

## Step 3. Find the brokerage account

Call `GET /v1/credit/tokenization/providers/{provider}/accounts` to list the
brokerage accounts you can use.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/credit/tokenization/providers/alpaca/accounts \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "providerAccountId": "a7c1e3f0-5d2b-4c8e-9f61-2b7d4e8a1c90",
      "status": "active",
      "displayName": "Treasury Brokerage Account"
    }
  ]
}
```

Use an account whose `status` is `active`.

## Step 4. Burn tokens and list eligible orders

Burn your tokens on Arc, and sell the underlying shares from the brokerage
account. Then call `GET /v1/credit/tokenization/providers/{provider}/orders`
with the account and the burn's transaction hash to list the sell orders that
can back the advance.

```bash theme={null}
curl "https://api-sandbox.circle.com/v1/credit/tokenization/providers/alpaca/orders?providerAccountId=a7c1e3f0-5d2b-4c8e-9f61-2b7d4e8a1c90&transactionHash=0x5ba3602c1ffcbac77db82bf1360fe44f2042042c782e9114ea29ecb1708c239f" \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "data": {
    "transactionHash": "0x5ba3602c1ffcbac77db82bf1360fe44f2042042c782e9114ea29ecb1708c239f",
    "symbol": "AAPL",
    "burnedShareQuantity": "100",
    "orders": [
      {
        "orderId": "e2f8a4c6-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
        "submittedAt": "2024-03-20T14:05:12.000Z",
        "fillStatus": "filled",
        "availableShares": "60",
        "weightedAveragePrice": "172.45",
        "advanceLimit": { "amount": "10347.00", "currency": "USD" }
      },
      {
        "orderId": "b9d7c5e3-a1f2-4d6b-8c0e-3f5a7b9d1e2c",
        "submittedAt": "2024-03-20T14:06:40.000Z",
        "fillStatus": "open",
        "availableShares": "50",
        "weightedAveragePrice": "172.30",
        "advanceLimit": { "amount": "8615.00", "currency": "USD" }
      }
    ]
  }
}
```

The list contains the account's sell orders for the burned token that were
submitted in the 2 hours before or after the burn and don't already back another
advance. For the full eligibility rules, see
[List eligible orders for a burn](https://developers.circle.com/api-reference/circle-mint/credit/list-tokenization-orders.md).

`weightedAveragePrice` is the value per share used for the advance, and
`advanceLimit` is the most you can borrow against that order alone. For how each
`fillStatus` is valued, see
[RWA Redemption Advance tokenization lifecycle](https://developers.circle.com/circle-mint/concepts/credit-api.md#rwa-redemption-advance-tokenization-lifecycle).

> [!NOTE]
>
> The list reflects live order and market data and does not reserve the orders.
> The values can change before you create the advance. The burn must be no more
> than 24 hours old, and a burn that already backs an advance returns HTTP 409.

## Step 5. Create the advance

Call `POST /v1/credit/tokenization/advances` with the burn's transaction hash,
the account, and the IDs of the orders to use. The orders' `availableShares`
must add up to at least `burnedShareQuantity`, the number of tokens burned. Each
token represents one share.

```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/credit/tokenization/advances \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "provider": "ALPACA",
    "providerAccountId": "a7c1e3f0-5d2b-4c8e-9f61-2b7d4e8a1c90",
    "transactionHash": "0x5ba3602c1ffcbac77db82bf1360fe44f2042042c782e9114ea29ecb1708c239f",
    "orders": [
      { "orderId": "e2f8a4c6-1b3d-4e5f-8a9b-0c1d2e3f4a5b" },
      { "orderId": "b9d7c5e3-a1f2-4d6b-8c0e-3f5a7b9d1e2c" }
    ],
    "amount": { "amount": "15000.00", "currency": "USD" }
  }'
```

```json theme={null}
{
  "data": {
    "id": "c4a2e6f8-3b1d-4f7a-9e2c-5d8b0a1f3e6c",
    "amount": { "amount": "15000.00", "currency": "USD" },
    "status": "requested",
    "accountId": "1000000",
    "createDate": "2024-03-20T14:10:02.000Z",
    "updateDate": "2024-03-20T14:10:02.000Z",
    "provider": "ALPACA",
    "providerAccountId": "a7c1e3f0-5d2b-4c8e-9f61-2b7d4e8a1c90",
    "transactionHash": "0x5ba3602c1ffcbac77db82bf1360fe44f2042042c782e9114ea29ecb1708c239f",
    "symbol": "AAPL",
    "burnedShareQuantity": "100",
    "orders": [
      {
        "orderId": "e2f8a4c6-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
        "submittedAt": "2024-03-20T14:05:12.000Z",
        "allocatedShares": "60",
        "weightedAveragePrice": "172.45"
      },
      {
        "orderId": "b9d7c5e3-a1f2-4d6b-8c0e-3f5a7b9d1e2c",
        "submittedAt": "2024-03-20T14:06:40.000Z",
        "allocatedShares": "40",
        "weightedAveragePrice": "172.30"
      }
    ]
  }
}
```

The `orders` in the response show the shares Circle counted for each order, up
to `burnedShareQuantity`. In this example, the filled order counts all 60 of its
shares, and the open order counts the 40 still needed. `amount` must not exceed
the value of the counted shares after the advance rate for the token. Here that
is 60 × 172.45 + 40 × 172.30 = 17,239.00 USD at the full rate. For how Circle
picks which shares to count, see
[RWA Redemption Advance tokenization lifecycle](https://developers.circle.com/circle-mint/concepts/credit-api.md#rwa-redemption-advance-tokenization-lifecycle).

The request is validated when you send it. There is no reserve step and no
manual review, so a valid request returns `requested` right away. Retrying with
the same `idempotencyKey` and body returns the original advance. A different
body with the same key returns HTTP 409.

> [!NOTE]
>
> To send the funds to a verified blockchain address instead of your Circle Mint
> wallet, add a `destination` with `type` set to `verified_blockchain`, as in
> the other credit transfer requests.

## Step 6. Observe disbursement

Poll `GET /v1/credit/tokenization/advances/{id}` until `status` is `disbursed`.

```bash theme={null}
curl https://api-sandbox.circle.com/v1/credit/tokenization/advances/c4a2e6f8-3b1d-4f7a-9e2c-5d8b0a1f3e6c \
  -H "Authorization: Bearer $API_KEY"
```

Once the advance is `disbursed`, the response adds `outstanding`, `fees`,
`dueDate`, and `disbursedDate`. To list your advances, call
`GET /v1/credit/tokenization/advances`, filtering by `status` or by create date
with `from` and `to`.

## Step 7. Repay the advance

Repay a tokenization advance the same way as any RWA Redemption Advance: by
wire, or with USDC from your Circle Mint wallet through
`POST /v1/credit/cryptoRepayment`. For details, see
[Repayment](https://developers.circle.com/circle-mint/concepts/credit-api.md#repayment).