Skip to main content
This quickstart walks through a complete Settlement Advance draw lifecycle: you check the credit line, reserve funds, send a wire and upload proof, observe disbursement and accrued fees, and then repay by wire and confirm the repayment. For the conceptual model behind these calls, see the Credit API concept page.

​
Prerequisites

Before you begin, make sure that you’ve:
  • Contacted your Circle representative to activate Settlement Advance on your Circle Mint account.
  • Confirmed your Circle Mint wallet holds the required USDC minBalance for your credit line.
  • Configured API authentication per Getting Started. Examples below use $API_KEY and the base URL https://api-sandbox.circle.com.
  • Identified the fiatAccountId of the wire bank account from which you’ll send the inbound wire to Circle.

​
Step 1. Check the credit line

Call GET /v1/credit to confirm your credit line is active and has sufficient capacity for the draw.
Before proceeding, confirm:
  • product is settlementAdvance.
  • available.amount covers the draw amount you plan to reserve.
  • validationErrors is an empty array.
For the meaning of each field, see the credit-line model.

​
Step 2. Get wire repayment instructions

Call GET /v1/credit/repaymentAccounts/{fiatAccountId} to retrieve wire instructions for the repayment account tied to your wire bank account.
The repayment account is unverified until Circle matches the first incoming wire repayment to it, after which it transitions to active. Cache the wireInstructions block—you reuse it when repaying in Step 6.
In the sandbox, simulate a matching wire and verify the account by posting a mock repayment.

​
Step 3. Reserve funds for the advance

Call POST /v1/credit/transfers/reserveFunds to hold capacity against your credit line while you initiate the supporting wire. To use Credit Express, include the optional destination field to disburse directly to a verified address from your Circle Mint recipient address book; omit it to land the disbursement in your Mint wallet.
Save the transfer id from the response—it identifies this draw for the remaining steps. Reservations expire 30 minutes after creation and only one can be open per credit line at a time; for the full set of constraints, see Settlement Advance lifecycle. If you can’t send the wire before the reservation expires, cancel it with PUT /v1/credit/transfers/{id}/cancelReserve to free the capacity immediately.
Settlement Advance cannot use POST /v1/credit/transfers to create a draw. That endpoint is for Line of Credit only and returns HTTP 400 for Settlement Advance credit lines. Use reserveFunds followed by requestReservedFunds.

​
Step 4. Send the wire and upload wire proof

Using the wire instructions from Step 2, instruct your bank to send a wire to Circle for the reserved amount. Then upload proof of the wire to request disbursement by calling PUT /v1/credit/transfers/{id}/requestReservedFunds with a multipart/form-data request. Accepted file types are application/pdf, image/jpeg, and image/png.
The transfer moves from funds_reserved to requested. Circle’s Treasury team manually reviews the wire proof. In the sandbox the request auto-approves quickly; in production, approval typically takes 20 minutes to 2 hours.

​
Step 5. Observe disbursement and fee accrual

Once Treasury approves the request, the transfer moves to disbursed and recurringFee begins accruing daily against the outstanding balance.

​
5.1. Poll the transfer

Call GET /v1/credit/transfers/{id} to inspect the disbursement, due date, and accrued fees.
The outstanding amount is the principal plus accrued fees. Each day the credit line is open with an outstanding balance, recurringFee is applied to the principal and added to fees.total. The dueDate is 7 days after disbursedDate for Settlement Advance. If you reserved with a Credit Express destination, the blockchainDestination block tracks the onchain leg separately from the credit transfer. The blockchainDestination.transferId references the underlying Circle Mint transfer once disbursement initiates onchain.

​
5.2. Subscribe to webhooks

For asynchronous updates, subscribe to creditTransfers, creditFees, and creditRepayments in the Circle Mint Console. Webhook payloads mirror the corresponding GET endpoints. See webhook topics for what each topic publishes.

​
Step 6. Repay by wire

Send a wire from the bank account from Step 2 to Circle for the outstanding amount (principal plus accrued fees). Use the wireInstructions you cached from Step 2. In the sandbox, simulate the wire by posting a mock repayment:

​
Step 7. Confirm the repayment

List repayments filtered to your transfer by calling GET /v1/credit/repayments?transferId={id} and confirm a record exists with type: fiat and status: completed.
paymentAmount is the total wire received and amountApplied is the portion applied to this transfer’s outstanding balance (principal plus fees). repaymentAccountId is the fiat account the wire was matched to—the same account whose wire instructions you retrieved in Step 2. Then call GET /v1/credit/transfers/{id} again and confirm the transfer is paid.
The transfer now shows status: paid, outstanding is zero, and fees.unpaid is zero—the draw lifecycle is complete.
Settlement Advance does not support crypto repayment. POST /v1/credit/cryptoRepayment returns HTTP 400 for Settlement Advance credit lines. Repay by wire only.