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 current fee rate 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,
    "floatingLimitApplied": false
  },
  "stableFxFeeInBps": "50",
  "isRepaymentAllowed": true,
  "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 lock a fee snapshot

To lock a fee snapshot 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 and locks the fee that applies to the advance. Only one reservation is active per credit line at a time, and a request with a different idempotencyKey replaces the active reservation.This step is optional. If you don’t need a fee snapshot, 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": "funds_reserved",
  "expirationDate": "2025-08-07T11:16:00Z",
  "createDate": "2025-08-07T11:01:00Z",
  "fee": {
    "currency": "USDC",
    "amount": "175.00"
  }
}

Get the Permit2 typed data to sign

Call the presign endpoint with the exchangeTradeId 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 '
{
  "exchangeTradeId": "${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 feeBps, the accruedFee, the dueDate, and any repayments. The accruedFee and dueDate are omitted until the advance is funded.

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",
  "contractTradeId": "b4cdae0f-9285-48bf-8abf-109ae0177621",
  "status": "disbursed",
  "advance": {
    "currency": "MXNB",
    "amount": "6020000.00"
  },
  "collateral": {
    "currency": "USDC",
    "amount": "350000.00"
  },
  "feeBps": "50",
  "accruedFee": {
    "currency": "USDC",
    "amount": "12.50"
  },
  "createDate": "2025-08-07T11:01:00Z",
  "fundedAt": "2025-08-07T11:02:00Z",
  "dueDate": "2025-08-14T11:02:00Z",
  "repayments": [],
  "fee": null,
  "feeCollectedAt": null
}

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 webhook notifications. For the full set of trade states, see Trade states.

Repay the advance

Send the repayment onchain to the repayment address on your credit line, then record it by calling the repayment endpoint. Repayments are applied first-in-first-out (FIFO) across outstanding transfers in the same currency, and any excess is recorded as a credit over-repayment. 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