How-to: Fund a trade with a settlement advance

This guide shows how to use your Circle credit line to fund the maker leg of a confirmed StableFX trade through delegate funding, instead of delivering your own inventory. You sign a Permit2 authorization with amount 0, Circle delivers the advanced currency onchain on your behalf, and you repay the advance later. For the reasoning behind credit lines, delegate funding, collateral, and fees, see Settlement advance.

StableFX uses a single endpoint for all API requests. The base URL is https://api.circle.com/. The StableFX API uses your API key for authentication and to determine which environment to use. The TEST environment executes against Arc testnet and returns mock data.When developing or testing your integration, you should use your TEST API key. When you are ready to move to production, just update your code to use your LIVE API key.

Prerequisites

Before you begin, make sure you’ve:

Been approved for a Settlement Advance credit line.
Set up a wallet or application that supports Ethereum Improvement Proposal 712 (EIP-712) signatures.
Granted a USDC allowance to the Permit2 contract. See How-to: Grant USDC Allowance to Permit2.
Obtained the ID of a confirmed trade.
Installed curl, or another HTTP client, on your development machine.

The examples use MXNB as the advanced base currency and USDC as the collateral currency on Arc. Amounts use the shape {"currency": "USDC", "amount": "350000.00"}.

Steps

Check available credit

Call the get credit line endpoint to confirm how much credit you have available and the fee schedule that applies to advances, expressed in basis points (bps).

curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/settlementAdvance/credit \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

Response

{
  "status": "active",
  "limit": {
    "currency": "USDC",
    "amount": "1000000.00"
  },
  "usage": {
    "used": "350000.00",
    "available": "650000.00",
    "availableInCurrencies": {
      "USDC": "650000.00",
      "MXNB": "11180000.00"
    },
    "outstandingTransfers": 3
  },
  "fees": {
    "recurringFee": "2",
    "drawFee": "10",
    "reservationFee": "5"
  },
  "createDate": "2025-08-07T11:01:00Z",
  "updateDate": "2025-08-07T11:01:00Z"
}

The availableInCurrencies map shows the available credit converted to each supported currency. Use it to confirm you have enough credit in the currency you plan to advance.

(Optional) Reserve credit

To hold capacity on your credit line before you fund a trade, reserve credit with the reserve endpoint. Provide an idempotencyKey and the advance currency and amount. A reservation holds the credit for about 15 minutes. You can have one active reservation per currency. While a reservation is active, a request for the same currency with a different idempotencyKey is rejected; cancel the active reservation first.This step is optional. If you don’t need to reserve credit, skip to the next step.

curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/settlementAdvance/reserve \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "3a1f8e2c-9b4d-4f6a-8c2e-1d5b7a9f0c34",
  "advance": {
    "currency": "MXNB",
    "amount": "6020000.00"
  }
}
'

Response

{
  "id": "f9d2c4a1-7e3b-4a8c-9f01-2b6d8e4a5c70",
  "amount": {
    "currency": "MXNB",
    "amount": "6020000.00"
  },
  "status": "active",
  "expirationDate": "2025-08-07T11:16:00Z",
  "createDate": "2025-08-07T11:01:00Z"
}

Get the Permit2 typed data to sign

Call the presign endpoint with the tradeId of the confirmed trade to get the Permit2 typed data to sign.

curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/signatures/settlementAdvance/presign \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tradeId": "${stablefx_trade_id}"
}
'

Response

{
  "advance": {
    "currency": "MXNB",
    "amount": "6020000.00"
  },
  "collateral": {
    "currency": "USDC",
    "amount": "350000.00"
  },
  "makerPermitTypedData": {
    "domain": {
      "name": "Permit2",
      "chainId": 5042002,
      "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
    },
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "TokenPermissions": [
        { "name": "token", "type": "address" },
        { "name": "amount", "type": "uint256" }
      ],
      "DelegateFundingAuthorization": [
        { "name": "id", "type": "uint256" },
        { "name": "funder", "type": "address" },
        { "name": "recipient", "type": "address" },
        { "name": "token", "type": "address" },
        { "name": "amount", "type": "uint256" }
      ],
      "PermitWitnessTransferFrom": [
        { "name": "permitted", "type": "TokenPermissions" },
        { "name": "spender", "type": "address" },
        { "name": "nonce", "type": "uint256" },
        { "name": "deadline", "type": "uint256" },
        { "name": "witness", "type": "DelegateFundingAuthorization" }
      ]
    },
    "primaryType": "DelegateFundingAuthorizationPermitWitnessTransferFrom",
    "message": {
      "permitted": {
        "token": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
        "amount": "0"
      },
      "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
      "nonce": "309585810",
      "deadline": "1770302983",
      "witness": {
        "id": "10",
        "funder": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
        "recipient": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
        "token": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
        "amount": "6020000000000"
      }
    }
  }
}

Note the following about the response:

primaryType is DelegateFundingAuthorizationPermitWitnessTransferFrom.
The witness is a DelegateFundingAuthorization with id (the onchain trade ID), funder, recipient, token, and amount.
permitted.amount is always 0. No tokens move from your wallet; Circle delivers the advanced currency on your behalf.
spender is the FxEscrow contract address.
The response also returns the advance and collateral amounts for the trade.

Sign the typed data

Using your EIP-712-capable wallet or application, sign the makerPermitTypedData returned in the previous step. The signature is a 65-byte hex string.For example, with a viem wallet client:

const signature: `0x${string}` = await walletClient.signTypedData({
  domain: makerPermitTypedData.domain,
  types: makerPermitTypedData.types,
  primaryType: makerPermitTypedData.primaryType,
  message: makerPermitTypedData.message,
});

Request the advance

Submit the signed authorization to the request advance endpoint. Include an idempotencyKey, the tradeId, the permit2 witness payload, and the signature. The request is idempotent on tradeId, and funding runs asynchronously.

curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/settlementAdvance \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "7c9e6f3a-2d18-4b5c-a0e7-9f4d1b8c63a2",
  "tradeId": "${stablefx_trade_id}",
  "permit2": {
    "permitted": {
      "token": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
      "amount": "0"
    },
    "spender": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
    "nonce": "309585810",
    "deadline": "1770302983",
    "witness": {
      "id": "10",
      "funder": "0xa8f94168b4981840ba27d423f4ad6332bedee006",
      "recipient": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
      "token": "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
      "amount": "6020000000000"
    }
  },
  "signature": "0xsignature"
}
'

Response

{
  "advanceId": "b27d4e91-3c6a-4f02-8d15-7e9a0c4b1f83",
  "tradeId": "c2558cd1-98b5-4ccd-90b8-96891512af20",
  "status": "requested"
}

Track the advance

Call the get advance endpoint with the advanceId to track the advance through its lifecycle. The response reports the status, the advance and collateral amounts, the fees object (unpaid and total), the dueDate, and any repayments. The fees.total, paidDate, and dueDate fields are omitted until the advance is paid.

curl --request GET \
  --url https://api.circle.com/v1/exchange/stablefx/settlementAdvance/${advance_id} \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}'

Response

{
  "advanceId": "b27d4e91-3c6a-4f02-8d15-7e9a0c4b1f83",
  "tradeId": "c2558cd1-98b5-4ccd-90b8-96891512af20",
  "status": "disbursed",
  "advance": {
    "currency": "MXNB",
    "amount": "6020000.00"
  },
  "collateral": {
    "currency": "USDC",
    "amount": "350000.00"
  },
  "fees": {
    "total": null,
    "unpaid": {
      "currency": "USDC",
      "amount": "12.50"
    }
  },
  "createDate": "2025-08-07T11:01:00Z",
  "updateDate": "2025-08-07T11:02:00Z",
  "paidDate": null,
  "dueDate": null,
  "repayments": []
}

To list multiple advances, call the list advances endpoint. It supports filtering by status and create-date range, and it paginates with the pageBefore and pageAfter parameters and a configurable pageSize.The delegate-funded webhooks confirm onchain delivery. The stablefx.trade.makerDelegateFunded event fires when Circle delivers the advanced currency, and the stablefx.contract.makerDelegateDeliver.failed event fires if delivery fails. To subscribe, see How-to: Set up a webhook endpoint. For the full set of trade states, see Trade states.

Repay the advance

Record a repayment against the credit line backing the advance by calling the repayment endpoint. Any excess beyond the outstanding balance is credited to your Circle Mint account balance. For USDC and EURC repayments, round the amount up to two decimal places; other stablecoins, such as MXNB, QCAD, AUDF, and ZARU, aren’t subject to rounding. The request is idempotent on idempotencyKey: a successful request returns 201, and reusing the same key with different parameters returns 409.

curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/settlementAdvance/repayment \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "d4b8a1f6-5c2e-4a90-b7d3-0e6f8c1a92b5",
  "amount": {
    "currency": "MXNB",
    "amount": "6020000.00"
  }
}
'

The repayment applies against your credit line rather than a specific advance, so the request body carries only the idempotencyKey and the amount.Response

{
  "id": "a3f7c2e9-6b14-4d80-9c5a-2e8f1b0d473c",
  "amount": {
    "currency": "MXNB",
    "amount": "6020000.00"
  },
  "status": "pending",
  "createDate": "2025-08-14T11:02:00Z",
  "updateDate": "2025-08-14T11:02:00Z"
}

​Prerequisites

​Steps

​See also

Prerequisites

Steps

See also