Quickstart: Settlement Advance

This quickstart walks you through a complete Settlement Advance draw lifecycle using the Credit API. You check your available credit, reserve funds, upload wire proof for Treasury review, and track the transfer through to disbursement.

Prerequisites

Before you begin, ensure you have:

An approved Settlement Advance credit facility with Circle. Contact your Circle representative if you haven’t completed the offline credit agreement.
A Circle Mint API key with the Credit API entitlement enabled.
Familiarity with Circle Mint authentication and idempotent requests.

Step 1: Check your credit line status

Before initiating a draw, verify that your credit line is active and has sufficient available credit. Call the GET /v1/credit endpoint to retrieve your credit line details.

curl --location --request GET 'https://api-sandbox.circle.com/v1/credit' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "product": "settlementAdvance",
    "status": "active",
    "limit": { "amount": "500000.00", "currency": "USD" },
    "used": { "amount": "100000.00", "currency": "USD" },
    "available": { "amount": "400000.00", "currency": "USD" },
    "outstandingTransfers": 1,
    "feeRates": { "drawFee": "0.02", "dailyFee": "0.0003" },
    "unpaidFees": { "amount": "0.00", "currency": "USD" },
    "minBalance": { "amount": "50000.00", "currency": "USD" },
    "validationErrors": [],
    "createDate": "2024-01-15T10:30:00.000Z",
    "updateDate": "2024-03-20T14:22:00.000Z"
  }
}

Confirm the following before proceeding:

status is active.
available.amount is greater than or equal to the amount you plan to reserve.
validationErrors is an empty array. If it contains errors such as INSUFFICIENT_BALANCE, PENDING_FEES, or OVERDUE_TRANSFERS, resolve them before you create a new transfer.

Step 2: Get wire instructions

Before initiating a draw, retrieve the wire transfer instructions for your credit line. Call GET /v1/credit/wireInstructions to get the beneficiary details and tracking reference you need when sending your wire.

curl --location --request GET 'https://api-sandbox.circle.com/v1/credit/wireInstructions' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "data": {
    "trackingRef": "CIR3XBZZ4N",
    "beneficiary": {
      "name": "CIRCLE INTERNET FINANCIAL INC",
      "address1": "1 Main Street",
      "address2": "Suite 1"
    },
    "beneficiaryBank": {
      "swiftCode": "SVBKUS6S",
      "routingNumber": "121140399",
      "accountNumber": "3302726104",
      "currency": "USD",
      "name": "SILICON VALLEY BANK",
      "address": "3003 TASMAN DRIVE",
      "city": "SANTA CLARA",
      "postalCode": "95054",
      "country": "US"
    }
  }
}

Use the trackingRef value as the reference on your wire transfer so that Circle can match the incoming payment to your credit line. Save the beneficiary bank details for use when initiating your wire.

Step 3: Reserve funds

The reserve step holds the requested amount for you while you initiate and confirm your wire transfer. Reserve funds against your credit line by calling POST /v1/credit/transfers/reserveFunds. This creates a transfer in funds_reserved status and holds the requested amount against your available credit.

curl --location --request POST 'https://api-sandbox.circle.com/v1/credit/transfers/reserveFunds' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "amount": { "amount": "100000.00", "currency": "USD" }
}'

Response

{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "funds_reserved",
    "expiresAt": "2024-03-20T15:00:00.000Z",
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-20T14:30:00.000Z"
  }
}

Save the transfer id from the response. You need it for the remaining steps.

Reserved funds expire after 30 minutes. If you don’t upload wire proof before the expiresAt timestamp, the reservation automatically transitions to expired status and the funds return to your available credit.

Only one transfer can be in funds_reserved status per credit line at a time. You must complete or cancel the current reservation before creating a new one.

Step 4: Upload wire proof

Using the beneficiary details and tracking reference from Step 2, initiate your wire transfer through your bank. Then upload proof of the wire to request disbursement. Call PUT /v1/credit/transfers/{id}/requestReservedFunds with a multipart/form-data request containing your wire proof document. Accepted file types are PDF (application/pdf), JPEG (image/jpeg), and PNG (image/png).

curl --location --request PUT 'https://api-sandbox.circle.com/v1/credit/transfers/fc988ed5-c129-4f70-a064-e5beb7eb8e32/requestReservedFunds' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'fileName="wire-confirmation.pdf"' \
--form 'fileContent=@"/path/to/wire-confirmation.pdf"'

Response

{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "requested",
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-20T14:45:00.000Z"
  }
}

The transfer status transitions from funds_reserved to requested. At this point, Circle’s Treasury team reviews the wire proof. No further action is required from you until the review completes.

Step 5: Track the transfer status

Monitor your transfer as it progresses through the review and disbursement process. You can poll the transfer endpoint or subscribe to webhook notifications.

Poll the transfer endpoint

Call GET /v1/credit/transfers/{id} to check the current transfer status.

curl --location --request GET 'https://api-sandbox.circle.com/v1/credit/transfers/fc988ed5-c129-4f70-a064-e5beb7eb8e32' \
--header 'Authorization: Bearer YOUR_API_KEY'

Once Treasury approves the transfer and disburses funds, the response reflects the disbursed status along with fee and repayment details:

Response

{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "disbursed",
    "outstanding": { "amount": "102000.00", "currency": "USD" },
    "fees": {
      "total": { "amount": "2000.00", "currency": "USD" },
      "unpaid": { "amount": "2000.00", "currency": "USD" }
    },
    "dueDate": "2024-04-20T00:00:00.000Z",
    "disbursedDate": "2024-03-21T10:00:00.000Z",
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-21T10:00:00.000Z"
  }
}

The outstanding amount includes the original draw plus any accrued fees. The dueDate indicates when repayment is expected. For real-time updates, subscribe to webhook notifications through the Circle Mint webhook management UI:

creditTransfers: Receive notifications whenever a transfer changes status, such as the transition from requested to disbursed.
creditFees: Receive notifications when fees are accrued against your outstanding transfers.
creditRepayments: Receive notifications when a repayment is received and allocated against your outstanding balance.

The Settlement Advance transfer follows this status lifecycle: funds_reserved -> requested -> disbursed -> paid A transfer can also reach expired (if the reservation times out), rejected (if Treasury declines the request), or past_due (if repayment is overdue).

In sandbox, Settlement Advance requests are auto-approved. To simulate a rejection, reserve funds with an amount of 119.53.

Cancel a reservation (optional)

If you need to cancel a reservation before uploading wire proof, call PUT /v1/credit/transfers/{id}/cancelReserve. You can only cancel a transfer that is in funds_reserved status.

curl --location --request PUT 'https://api-sandbox.circle.com/v1/credit/transfers/fc988ed5-c129-4f70-a064-e5beb7eb8e32/cancelReserve' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "data": {
    "id": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
    "amount": { "amount": "100000.00", "currency": "USD" },
    "status": "canceled",
    "createDate": "2024-03-20T14:30:00.000Z",
    "updateDate": "2024-03-20T14:50:00.000Z"
  }
}

After cancellation, the reserved amount returns to your available credit and you can create a new reservation.

Mint

StableFX

​Prerequisites

​Step 1: Check your credit line status

​Step 2: Get wire instructions

​Step 3: Reserve funds

​Step 4: Upload wire proof

​Step 5: Track the transfer status

​Poll the transfer endpoint

​Subscribe to webhook notifications

​Cancel a reservation (optional)

Prerequisites

Step 1: Check your credit line status

Step 2: Get wire instructions

Step 3: Reserve funds

Step 4: Upload wire proof

Step 5: Track the transfer status

Poll the transfer endpoint

Subscribe to webhook notifications

Cancel a reservation (optional)