Skip to main content
POST
/
v1
/
exchange
/
stablefx
/
settlementAdvance
Request a settlement advance
curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/settlementAdvance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "tradeId": "trade-abc-123",
  "permit2": {
    "permitted": {
      "token": "0xTOKEN",
      "amount": "1000"
    },
    "spender": "0xFxEscrow000000000000000000000000000000000",
    "nonce": "1234567890",
    "deadline": "1782556800",
    "witness": {
      "id": "987654321",
      "funder": "0xLLCFunderPW...address",
      "recipient": "0xLLCEscrowPW...address",
      "token": "0xMXNB...address",
      "amount": "19000000000000000000000"
    }
  },
  "signature": "0x6f5a...c1b9"
}
'
{
  "advanceId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "tradeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "status": "disbursed"
}

Authorizations

​
Authorization
string
header
required

Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are requred to make a successful request.

Body

application/json

Request body for accepting a settlement advance by submitting a Permit2 signature.

​
idempotencyKey
string<uuid>
required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. To create a UUIDv4 go to uuidgenerator.net. If the same key is reused, it will be treated as the same request and the original response will be returned.

Example:

"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

​
tradeId
string
required

Trade identifier.

Example:

"trade-abc-123"

​
permit2
object
required

Permit2 PermitWitnessTransferFrom payload with DelegateFundingAuthorization witness. The permitted.amount is always 0 -- Permit2 is used as an authorization carrier, no tokens transfer from the maker.

​
signature
string
required

Maker's Permit2 signature over the typed data (0x-prefixed, 65 bytes hex).

Example:

"0x6f5a...c1b9"

Response

Settlement advance requested; funding in progress.

Settlement advance accepted; funding in progress.

​
advanceId
string<uuid>
required

System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

​
tradeId
string<uuid>
required

System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

​
status
enum<string>
required

Lifecycle status of the credit advanced against a settlement.

  • funds_reserved -- credit reserved on the line, awaiting maker action.
  • requested -- maker submitted the request; Circle is moving funds.
  • disbursed -- funds delivered to the funder passthrough wallet.
  • past_due -- repayment window has elapsed without full repayment.
  • paid -- credit fully repaid.
  • rejected -- credit line rejected the advance request.
  • expired -- reservation expired before being consumed.
  • canceled -- maker or Circle canceled the advance.
Available options:
funds_reserved,
requested,
disbursed,
past_due,
paid,
rejected,
expired,
canceled
Example:

"disbursed"