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

# How-to: Fund a trade with a settlement advance

> Use your Settlement Advance credit line to fund the maker leg of a confirmed StableFX trade through delegate funding.

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/concepts/settlement-advance).

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

## 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](/stablefx/howtos/grant-usdc-allowance-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

<Steps>
  <Step title="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).

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

    **Response**

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="(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.

    ```bash theme={null}
    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**

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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**

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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:

    ```typescript theme={null}
    const signature: `0x${string}` = await walletClient.signTypedData({
      domain: makerPermitTypedData.domain,
      types: makerPermitTypedData.types,
      primaryType: makerPermitTypedData.primaryType,
      message: makerPermitTypedData.message,
    });
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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**

    ```json theme={null}
    {
      "advanceId": "b27d4e91-3c6a-4f02-8d15-7e9a0c4b1f83",
      "tradeId": "c2558cd1-98b5-4ccd-90b8-96891512af20",
      "status": "requested"
    }
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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**

    ```json theme={null}
    {
      "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](/api-reference/webhook-endpoints). For the
    full set of trade states, see [Trade states](/stablefx/references/trade-states).
  </Step>

  <Step title="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`.

    ```bash theme={null}
    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**

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>
</Steps>

## See also

* [Settlement advance](/stablefx/concepts/settlement-advance)
* [Quickstart: Fulfill an FX trade as a maker](/stablefx/quickstarts/fx-trade-maker)