The Credit API is the borrower-facing programmatic interface to Circle Mint’s two credit facilities: Settlement Advance and Line of Credit. It exposes endpoints underDocumentation Index
Fetch the complete documentation index at: https://developers.circle.com/llms.txt
Use this file to discover all available pages before exploring further.
/v1/credit/ that you use to inspect your credit line, initiate
draws, follow disbursement, and process repayments in fiat or crypto.
For step-by-step procedural walkthroughs, see the
Settlement Advance quickstart and
the Line of Credit quickstart.
The Credit API requires three things before activation: an executed Core API
Agreement, a separate offline credit contract with Circle, and the Credit API
entitlement enabled on your account. To start the process,
contact Circle to discuss credit products
and request that the Credit API entitlement be enabled.
Two products: Settlement Advance and Line of Credit
The Credit API surfaces two distinct products. A given customer holds one credit line for one product; the product determines how draws are requested, how fees accrue, and which repayment paths are available.| Settlement Advance | Line of Credit | |
|---|---|---|
| Target use case | Covers settlement-timing gaps for customers on slow fiat rails, such as OTC desks, capital markets firms, and payment companies. You prefund a settlement and request the advance against it. | Provides fast, automated drawdowns for ongoing liquidity needs. Suited to customers who want programmatic access to working capital without per-draw manual review. |
| Draw mechanics | Reserve-then-request flow: you reserve funds, wire USD to Circle, upload the wire proof, and Circle’s Treasury team approves the disbursement. | Auto-approved single request: a POST /v1/credit/transfers call moves the transfer through requested and into disbursed without manual review. |
| Repayment paths | Fiat only. You wire USD to a Circle-issued repayment account. | Fiat (wire) or crypto. Crypto repayments deduct USDC from your Circle Mint wallet. |
feeCadence options | daily only. Recurring fees accrue every 24 hours and repayment is due 7 days after disbursement. | daily or hourly. Hourly cadence accrues fees every hour with a 24-hour repayment window, sized for capital-markets workflows that need same-day repayment turns. |
The credit-line model
Your credit line is the facility object the Credit API revolves around. Every draw, fee, and repayment is recorded against it.GET /v1/credit returns the
current state of the line. The subsections below explain the parts of that model
you should be most familiar with.
One credit line per customer, scoped to a product
A Circle Mint customer has at most one credit line, and the line is scoped to a singleproduct: either settlementAdvance or lineOfCredit. The settlement
currency is USD. If your business needs both products, that requires a separate
contractual conversation with Circle, not a second credit line on the same
account.
Fee rates
The credit line’sfeeRates object captures the two rates that can apply to a
draw:
drawFee: A one-time fee assessed at disbursement. Only Settlement Advance usesdrawFee; Line of Credit does not charge a per-draw fee.recurringFee: A fee that accrues against the outstanding balance at the cadence defined byfeeCadence. Both products userecurringFee.
recurringFee of 0.001 represents a 0.1% rate. Fees accrue automatically
and are deducted from your Circle Mint wallet balance.
Fee cadence and repayment timing
feeCadence controls how often recurringFee accrues and how soon a disbursed
transfer must be repaid:
daily: Fees accrue every 24 hours. Each disbursed transfer is due 7 days after disbursement.hourly: Fees accrue every hour. Each disbursed transfer is due 24 hours after disbursement. Hourly cadence is available on Line of Credit only and is designed for trading and capital-markets workflows that recycle capital intraday.
Minimum balance
The credit line carries aminBalance requirement: the USDC balance you must
keep in your Circle Mint wallet while the credit line is active. The minimum
balance is an operating constraint that supports fee deduction and crypto
repayment for Line of Credit customers; falling below it surfaces as a
validation error that blocks new draws.
Validation errors
validationErrors is a list of blocking conditions on new transfer creation.
When it is non-empty, the credit line cannot originate new transfers and the
relevant create-transfer endpoints return HTTP 400 until the conditions clear.
Three codes can appear:
INSUFFICIENT_BALANCE: The Circle Mint wallet’s USDC balance is belowminBalance.PENDING_FEES: Accrued fees are still pending settlement against the wallet.OVERDUE_TRANSFERS: At least one disbursed transfer has passed its due date without being fully repaid.
validationErrors as constraints to check before initiating a draw. The
quickstarts cover how to resolve each condition operationally.
Credit transfer lifecycle
A credit transfer is one draw against your credit line. The two products follow different lifecycles because Settlement Advance involves a reserve-then-request handshake with manual Treasury approval, while Line of Credit auto-approves on request.Settlement Advance lifecycle
A Settlement Advance transfer starts when you reserve funds and ends when the disbursed amount is fully repaid. The reservation step exists so you can lock in capacity against your line while you initiate the supporting wire.funds_reserved: Capacity is reserved against your credit line. The reservation expires after 30 minutes if it is not progressed torequested, and only one transfer at a time may be in this state per credit line.requested: You have submitted wire proof for the reserved transfer and Circle’s Treasury team is reviewing the request.disbursed: Treasury has approved the advance and the funds have landed in your Mint wallet (or, with Credit Express, at the verified blockchain destination).paid: The disbursed amount has been fully repaid.expired: The reservation timed out before it was progressed torequested.canceled: You canceled the reservation before submitting wire proof.rejected: Treasury declined the request.past_due: The disbursed amount has not been fully repaid by its due date.
Line of Credit lifecycle
A Line of Credit transfer skips the reservation step. A single create request moves the transfer torequested and Circle auto-disburses it.
requested: The draw has been created and is being processed for disbursement.disbursed: Funds have landed in your Mint wallet (or at the verified blockchain destination when Credit Express is configured).paid: The disbursed amount has been fully repaid.rejected: Circle declined the request.past_due: The disbursed amount has not been fully repaid by its due date.
Credit Express
Credit Express is an optional destination configuration for a credit transfer. Instead of disbursing into your Circle Mint wallet, Circle sends the USDC directly onchain to a verified address from your Circle Mint recipient address book. Credit Express is available on both Settlement Advance and Line of Credit. The feature requires that the destination address is already registered and verified through the recipient address book; you cannot register a new address as part of a draw. When a transfer is configured with a Credit Express destination, the disbursement carries an additional onchain delivery status that progresses throughpending, initiated, complete, and failed. That status is
separate from the credit transfer’s own status—the transfer reflects the credit
relationship between you and Circle, while the destination status reflects the
onchain leg of the disbursement.
Repayment
Repayments retire outstanding balances on disbursed transfers. The Credit API supports two repayment paths; product choice determines which paths are available.Fiat repayment
Fiat repayment is available for both Settlement Advance and Line of Credit. You wire USD to a Circle-issued repayment account; Circle matches the incoming wire to your credit line and applies it against outstanding transfers. The repayment account is initiallyunverified and stays in that state until the first
incoming wire is matched to it, at which point it transitions to active. The
account’s wire instructions remain stable across that transition.
Crypto repayment
Crypto repayment is available for Line of Credit only. Circle deducts USDC from your Circle Mint wallet and applies it to outstanding transfers. The repayment amount is capped at the current outstanding balance—you cannot prepay beyond what is owed. Settlement Advance does not support crypto repayment; calls to the crypto repayment endpoint against a Settlement Advance credit line return HTTP 400.Webhook topics
The Credit API publishes three webhook topics so your server can follow credit activity asynchronously rather than polling. Subscribe to whichever topics match the events you need to react to. Payloads mirror the correspondingGET
endpoints, so a notification carries the same shape your code already handles
when fetching a single resource.
creditTransfers: Fires when a credit transfer changes status—for example, when a Settlement Advance request is approved and moves todisbursed, or when a transfer becomespast_due.creditFees: Fires when a fee accrues against the credit line. Cadence matchesfeeCadence, so daily lines emit fee notifications every 24 hours while hourly Line of Credit lines emit them every hour.creditRepayments: Fires when Circle matches an incoming wire repayment or records a completed crypto repayment.