Request a settlement advance

curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/settlementAdvances \
  --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": "5000000000"
    }
  },
  "signature": "0x6f5a...c1b9"
}
'

import requests

url = "https://api.circle.com/v1/exchange/stablefx/settlementAdvances"

payload = {
    "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": "5000000000"
        }
    },
    "signature": "0x6f5a...c1b9"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: '5000000000'
      }
    },
    signature: '0x6f5a...c1b9'
  })
};

fetch('https://api.circle.com/v1/exchange/stablefx/settlementAdvances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.circle.com/v1/exchange/stablefx/settlementAdvances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => '5000000000'
        ]
    ],
    'signature' => '0x6f5a...c1b9'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.circle.com/v1/exchange/stablefx/settlementAdvances"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"tradeId\": \"trade-abc-123\",\n  \"permit2\": {\n    \"permitted\": {\n      \"token\": \"0xTOKEN\",\n      \"amount\": \"1000\"\n    },\n    \"spender\": \"0xFxEscrow000000000000000000000000000000000\",\n    \"nonce\": \"1234567890\",\n    \"deadline\": \"1782556800\",\n    \"witness\": {\n      \"id\": \"987654321\",\n      \"funder\": \"0xLLCFunderPW...address\",\n      \"recipient\": \"0xLLCEscrowPW...address\",\n      \"token\": \"0xMXNB...address\",\n      \"amount\": \"5000000000\"\n    }\n  },\n  \"signature\": \"0x6f5a...c1b9\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.circle.com/v1/exchange/stablefx/settlementAdvances")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"tradeId\": \"trade-abc-123\",\n  \"permit2\": {\n    \"permitted\": {\n      \"token\": \"0xTOKEN\",\n      \"amount\": \"1000\"\n    },\n    \"spender\": \"0xFxEscrow000000000000000000000000000000000\",\n    \"nonce\": \"1234567890\",\n    \"deadline\": \"1782556800\",\n    \"witness\": {\n      \"id\": \"987654321\",\n      \"funder\": \"0xLLCFunderPW...address\",\n      \"recipient\": \"0xLLCEscrowPW...address\",\n      \"token\": \"0xMXNB...address\",\n      \"amount\": \"5000000000\"\n    }\n  },\n  \"signature\": \"0x6f5a...c1b9\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/exchange/stablefx/settlementAdvances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"tradeId\": \"trade-abc-123\",\n  \"permit2\": {\n    \"permitted\": {\n      \"token\": \"0xTOKEN\",\n      \"amount\": \"1000\"\n    },\n    \"spender\": \"0xFxEscrow000000000000000000000000000000000\",\n    \"nonce\": \"1234567890\",\n    \"deadline\": \"1782556800\",\n    \"witness\": {\n      \"id\": \"987654321\",\n      \"funder\": \"0xLLCFunderPW...address\",\n      \"recipient\": \"0xLLCEscrowPW...address\",\n      \"token\": \"0xMXNB...address\",\n      \"amount\": \"5000000000\"\n    }\n  },\n  \"signature\": \"0x6f5a...c1b9\"\n}"

response = http.request(request)
puts response.read_body

{
  "advanceId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "tradeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "status": "disbursed"
}

{
  "message": "Unknown error occurred",
  "errors": [
    {
      "error": "MISSING_OR_INVALID_FIELD",
      "message": "<string>",
      "location": "<string>"
    }
  ]
}

{
  "message": "Unknown error occurred",
  "errors": [
    {
      "error": "MISSING_OR_INVALID_FIELD",
      "message": "<string>",
      "location": "<string>"
    }
  ]
}

{
  "message": "Unknown error occurred",
  "errors": [
    {
      "error": "MISSING_OR_INVALID_FIELD",
      "message": "<string>",
      "location": "<string>"
    }
  ]
}

{
  "message": "Unknown error occurred",
  "errors": [
    {
      "error": "MISSING_OR_INVALID_FIELD",
      "message": "<string>",
      "location": "<string>"
    }
  ]
}

Request a settlement advance

Submit the Permit2 signature generated from the presign endpoint along with the witness payload. Funding runs asynchronously after this call returns.

Idempotent on tradeId: replays for the same trade either return the in-progress settlement advance or short-circuit when the trade already has a non-failed active settlement advance.

Calling /reserve first is optional. The request body is the same whether or not a prior reservation exists.

Collateral rounding: when the repayment is complete and collateral is released, Circle rounds the collateral amount to 2 decimal places.

POST

exchange

stablefx

settlementAdvances

Request a settlement advance

curl --request POST \
  --url https://api.circle.com/v1/exchange/stablefx/settlementAdvances \
  --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": "5000000000"
    }
  },
  "signature": "0x6f5a...c1b9"
}
'

import requests

url = "https://api.circle.com/v1/exchange/stablefx/settlementAdvances"

payload = {
    "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": "5000000000"
        }
    },
    "signature": "0x6f5a...c1b9"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: '5000000000'
      }
    },
    signature: '0x6f5a...c1b9'
  })
};

fetch('https://api.circle.com/v1/exchange/stablefx/settlementAdvances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.circle.com/v1/exchange/stablefx/settlementAdvances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => '5000000000'
        ]
    ],
    'signature' => '0x6f5a...c1b9'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.circle.com/v1/exchange/stablefx/settlementAdvances"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"tradeId\": \"trade-abc-123\",\n  \"permit2\": {\n    \"permitted\": {\n      \"token\": \"0xTOKEN\",\n      \"amount\": \"1000\"\n    },\n    \"spender\": \"0xFxEscrow000000000000000000000000000000000\",\n    \"nonce\": \"1234567890\",\n    \"deadline\": \"1782556800\",\n    \"witness\": {\n      \"id\": \"987654321\",\n      \"funder\": \"0xLLCFunderPW...address\",\n      \"recipient\": \"0xLLCEscrowPW...address\",\n      \"token\": \"0xMXNB...address\",\n      \"amount\": \"5000000000\"\n    }\n  },\n  \"signature\": \"0x6f5a...c1b9\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.circle.com/v1/exchange/stablefx/settlementAdvances")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"tradeId\": \"trade-abc-123\",\n  \"permit2\": {\n    \"permitted\": {\n      \"token\": \"0xTOKEN\",\n      \"amount\": \"1000\"\n    },\n    \"spender\": \"0xFxEscrow000000000000000000000000000000000\",\n    \"nonce\": \"1234567890\",\n    \"deadline\": \"1782556800\",\n    \"witness\": {\n      \"id\": \"987654321\",\n      \"funder\": \"0xLLCFunderPW...address\",\n      \"recipient\": \"0xLLCEscrowPW...address\",\n      \"token\": \"0xMXNB...address\",\n      \"amount\": \"5000000000\"\n    }\n  },\n  \"signature\": \"0x6f5a...c1b9\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/exchange/stablefx/settlementAdvances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11\",\n  \"tradeId\": \"trade-abc-123\",\n  \"permit2\": {\n    \"permitted\": {\n      \"token\": \"0xTOKEN\",\n      \"amount\": \"1000\"\n    },\n    \"spender\": \"0xFxEscrow000000000000000000000000000000000\",\n    \"nonce\": \"1234567890\",\n    \"deadline\": \"1782556800\",\n    \"witness\": {\n      \"id\": \"987654321\",\n      \"funder\": \"0xLLCFunderPW...address\",\n      \"recipient\": \"0xLLCEscrowPW...address\",\n      \"token\": \"0xMXNB...address\",\n      \"amount\": \"5000000000\"\n    }\n  },\n  \"signature\": \"0x6f5a...c1b9\"\n}"

response = http.request(request)
puts response.read_body

{
  "advanceId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "tradeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
  "status": "disbursed"
}

{
  "message": "Unknown error occurred",
  "errors": [
    {
      "error": "MISSING_OR_INVALID_FIELD",
      "message": "<string>",
      "location": "<string>"
    }
  ]
}

{
  "message": "Unknown error occurred",
  "errors": [
    {
      "error": "MISSING_OR_INVALID_FIELD",
      "message": "<string>",
      "location": "<string>"
    }
  ]
}

{
  "message": "Unknown error occurred",
  "errors": [
    {
      "error": "MISSING_OR_INVALID_FIELD",
      "message": "<string>",
      "location": "<string>"
    }
  ]
}

{
  "message": "Unknown error occurred",
  "errors": [
    {
      "error": "MISSING_OR_INVALID_FIELD",
      "message": "<string>",
      "location": "<string>"
    }
  ]
}

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

Show child attributes

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"

Get settlement advance Permit2 typed data for signing

Get settlement advance detail

⌘I