Credit API

Understand how the Credit API exposes Circle Mint’s Settlement Advance, RWA Redemption Advance, and Line of Credit products, the credit-line model, and the lifecycle of credit transfers and repayments.

The Credit API is the borrower-facing programmatic interface to Circle Mint’s three credit facilities: Settlement Advance, RWA Redemption Advance, and Line of Credit. It exposes endpoints under /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.

Products: Settlement Advance, RWA Redemption Advance, and Line of Credit

The Credit API surfaces three 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	RWA Redemption 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.	Covers redemption-timing gaps for Real World Asset (RWA) issuers and participants. Advances USD against an onchain token burn on Arc.	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.	Reserve-then-request flow: you reserve funds, submit the onchain Arc burn transactionHash with receipt 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.	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; daily cadence accrues fees every 24 hours with a 7-day repayment window.	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 single product: settlementAdvance, rwaRedemptionAdvance, or lineOfCredit. The settlement currency is USD. If your business needs multiple products, that requires a separate contractual conversation with Circle, not multiple credit lines on the same account.

Fee rates

The credit line’s feeRates object captures the two rates that can apply to a draw:

• drawFee: A one-time fee assessed at disbursement. Settlement Advance and RWA Redemption Advance use drawFee; Line of Credit does not charge a per-draw fee.
• recurringFee: A fee that accrues against the outstanding balance at the cadence defined by feeCadence. All three products use recurringFee.

Both rates are decimal multipliers applied to the transfer amount. For example, a 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 and RWA Redemption Advance lines, and is designed for trading, redemption, and capital-markets workflows that recycle capital intraday.

Minimum balance

The credit line carries a minBalance 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 below minBalance.
• 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.

Treat 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 products follow different lifecycles because Settlement Advance and RWA Redemption Advance involve a reserve-then-request handshake with Treasury approval, while Line of Credit auto-approves on request.

Settlement Advance lifecycle

A Settlement Advance or RWA Redemption 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 (for Settlement Advance) or submit the onchain Arc burn transactionHash with receipt proof (for RWA Redemption Advance). Both products follow the same transfer state machine:

• funds_reserved: Capacity is reserved against your credit line. The reservation expires after 30 minutes if it is not progressed to requested, and only one transfer at a time may be in this state per credit line.
• requested: You have submitted wire proof (for Settlement Advance) or the onchain Arc burn transactionHash and receipt proof (for RWA Redemption Advance). 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 to requested.
• canceled: You canceled the reservation before submitting 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 to requested 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 Settlement Advance, RWA Redemption 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 through pending, 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 all three credit products. 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 initially unverified 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.

Each fiat repayment record exposes repaymentAccountId, the identifier of the fiat account the repayment was applied to. Pass it to GET /v1/credit/repaymentAccounts/{fiatAccountId} to retrieve the account’s bank details and wire instructions. The field is present for fiat repayments with a linked account and omitted for crypto repayments.

Crypto repayment

Crypto repayment is available for Line of Credit and RWA Redemption Advance lines. 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.

Account attribution

Credit transfer, fee, and crypto repayment records each expose accountId, the identifier of the Circle account the funds moved through. This is distinct from repaymentAccountId, which identifies the fiat bank account used for a fiat repayment.

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 corresponding GET 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 to disbursed, or when a transfer becomes past_due.
• creditFees: Fires when a fee accrues against the credit line. Cadence matches feeCadence, 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. The payload includes repaymentAccountId for fiat repayments, so you can reconcile the repayment to its bank account without an extra lookup.