Quickstart: Draw an RWA redemption advance with brokerage orders

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

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.

Step 2. Confirm the tokenization flow

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

curl https://api-sandbox.circle.com/v1/credit/tokenization/providers \
  -H "Authorization: Bearer $API_KEY"

{
  "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.

curl https://api-sandbox.circle.com/v1/credit/tokenization/providers/alpaca/accounts \
  -H "Authorization: Bearer $API_KEY"

{
  "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.

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"

{
  "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. 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.

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.

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" }
  }'

{
  "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. 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.

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.

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.

Mint

Match

StableFX

Digital Asset Accounts

End User Onboarding

Quickstart: Draw an RWA redemption advance with brokerage orders

Prerequisites

Step 1. Check the credit line

Step 2. Confirm the tokenization flow

Step 3. Find the brokerage account

Step 4. Burn tokens and list eligible orders

Step 5. Create the advance

Step 6. Observe disbursement

Step 7. Repay the advance

​Prerequisites

​Step 1. Check the credit line

​Step 2. Confirm the tokenization flow

​Step 3. Find the brokerage account

​Step 4. Burn tokens and list eligible orders

​Step 5. Create the advance

​Step 6. Observe disbursement

​Step 7. Repay the advance

Prerequisites

Step 1. Check the credit line

Step 2. Confirm the tokenization flow

Step 3. Find the brokerage account

Step 4. Burn tokens and list eligible orders

Step 5. Create the advance

Step 6. Observe disbursement

Step 7. Repay the advance