> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}. > Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts. > Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md. > Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md. > Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers. > Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews. > Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming. > Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md. > Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors. > API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product. > Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes. > When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records. > Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md. # Quickstart: Draw and repay a line of credit > Check your credit line, request an auto-disbursed draw, observe fees, and repay with crypto or wire to close out a Line of Credit transfer. This quickstart walks through a complete Line of Credit draw lifecycle: you check the credit line, request a draw that auto-disburses, observe accrued fees, repay using USDC from your Circle Mint wallet (or by wire as a fallback), and confirm the transfer closes out. For the conceptual model behind these calls, see the [Credit API](/circle-mint/concepts/credit-api) concept page. ## Prerequisites Before you begin, make sure that you've: * Contacted your Circle representative to activate Line of Credit 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](/circle-mint/quickstarts/getting-started). Examples below use `$API_KEY` and the base URL `https://api-sandbox.circle.com`. * Identified the `fiatAccountId` of a wire bank account if you intend to use wire repayment as a fallback in Step 2. * Reviewed the Line of Credit agreement under the **Agreement** tab in the [Mint Console](https://app.circle.com/credit/agreement). Your use of Line of Credit is governed by this agreement. ## Step 1. Check the credit line Call `GET /v1/credit` to confirm your credit line is active and has sufficient capacity for the draw. ```bash theme={null} curl https://api-sandbox.circle.com/v1/credit \ -H "Authorization: Bearer $API_KEY" ``` ```json theme={null} { "data": { "id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0", "product": "lineOfCredit", "feeCadence": "daily", "status": "active", "limit": { "amount": "1000000.00", "currency": "USD" }, "used": { "amount": "250000.00", "currency": "USD" }, "available": { "amount": "750000.00", "currency": "USD" }, "outstandingTransfers": 2, "feeRates": { "recurringFee": "0.0003" }, "unpaidFees": { "amount": "0.00", "currency": "USD" }, "minBalance": { "amount": "100000.00", "currency": "USD" }, "validationErrors": [], "createDate": "2024-01-15T10:30:00.000Z", "updateDate": "2024-03-20T14:22:00.000Z" } } ``` Before proceeding, confirm: * `product` is `lineOfCredit`. * `available.amount` covers the draw amount you plan to request. * `validationErrors` is an empty array. If `validationErrors` is non-empty, resolve each entry before requesting a draw: * `INSUFFICIENT_BALANCE`: top up your Circle Mint USDC wallet to at least the credit line's `minBalance`. * `PENDING_FEES`: wait for pending fees to settle, or repay them with `POST /v1/credit/cryptoRepayment`. * `OVERDUE_TRANSFERS`: repay overdue transfers by wire or crypto repayment to clear the block. ## Step 2. Get wire repayment instructions (optional fallback) Line of Credit supports crypto repayment directly from your Circle Mint wallet, so wire instructions are only needed if you plan to repay by wire. To retrieve them, call `GET /v1/credit/repaymentAccounts/{fiatAccountId}` with the ID of the wire bank account you'll send from. ```bash theme={null} curl https://api-sandbox.circle.com/v1/credit/repaymentAccounts/b8627ae8-732b-4d25-b947-1df8f4007a29 \ -H "Authorization: Bearer $API_KEY" ``` ```json theme={null} { "data": { "id": "c9f2a1b3-6d84-4e0f-b512-9a8c7e3d4f01", "description": "WELLS FARGO BANK, NA ****1111", "status": "unverified", "wireInstructions": { "trackingRef": "CIR3XBZZ4N", "beneficiary": { "name": "CIRCLE INTERNET FINANCIAL INC", "address1": "1 Main Street", "address2": "Suite 1" }, "beneficiaryBank": { "swiftCode": "CRYPTO99", "routingNumber": "999999999", "accountNumber": "3302726104", "currency": "USD", "name": "CIRCLE BANKING PARTNER", "address": "100 MAIN STREET", "city": "NEW YORK", "postalCode": "10001", "country": "US" } } } } ``` The repayment account is `unverified` until Circle matches the first incoming wire repayment to it, after which it transitions to `active`. In the sandbox, simulate a matching wire and verify the account by posting a mock repayment. ```bash theme={null} curl -X POST https://api-sandbox.circle.com/v1/credit/mocks/repayments \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "fiatAccountId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "amount": { "amount": "50000.00", "currency": "USD" } }' ``` ```json theme={null} { "data": { "trackingRef": "CIR3XBZZ4N", "amount": { "amount": "50000.00", "currency": "USD" }, "status": "pending" } } ``` ## Step 3. Request a draw Call `POST /v1/credit/transfers` with an idempotency key and the draw amount. 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. Line of Credit draws auto-disburse—no manual review is required. ```bash theme={null} curl -X POST https://api-sandbox.circle.com/v1/credit/transfers \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7", "amount": { "amount": "50000.00", "currency": "USD" }, "destination": { "type": "verified_blockchain", "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab" } }' ``` ```json theme={null} { "data": { "id": "a1c2e3f4-5678-4d90-b123-456789abcdef", "amount": { "amount": "50000.00", "currency": "USD" }, "status": "requested", "blockchainDestination": { "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "status": "pending" }, "createDate": "2024-03-20T14:20:00.000Z", "updateDate": "2024-03-20T14:20:00.000Z" } } ``` Save the transfer `id` from the response—it identifies this draw for the remaining steps. The transfer starts in `requested` and transitions automatically to `disbursed` once funds land in your Mint wallet, or onchain at the verified address if you supplied a `destination`. For details on the blockchain destination, see [Credit Express](/circle-mint/concepts/credit-api#credit-express). ## Step 4. Observe disbursement and fee accrual Once the transfer is `disbursed`, `recurringFee` begins accruing against the outstanding balance at the credit line's cadence. ### 4.1. Poll the transfer Call `GET /v1/credit/transfers/{id}` to inspect the disbursement, due date, and accrued fees. ```bash theme={null} curl https://api-sandbox.circle.com/v1/credit/transfers/a1c2e3f4-5678-4d90-b123-456789abcdef \ -H "Authorization: Bearer $API_KEY" ``` ```json theme={null} { "data": { "id": "a1c2e3f4-5678-4d90-b123-456789abcdef", "amount": { "amount": "50000.00", "currency": "USD" }, "status": "disbursed", "outstanding": { "amount": "50150.00", "currency": "USD" }, "fees": { "total": { "amount": "150.00", "currency": "USD" }, "unpaid": { "amount": "150.00", "currency": "USD" } }, "dueDate": "2024-03-27T14:22:00.000Z", "disbursedDate": "2024-03-20T14:22:00.000Z", "blockchainDestination": { "addressId": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "status": "complete", "transferId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321" }, "createDate": "2024-03-20T14:20:00.000Z", "updateDate": "2024-03-21T00:00:00.000Z" } } ``` The `outstanding` amount is the principal plus accrued fees. For hourly cadence, fees accrue every hour and the `dueDate` is 24 hours after `disbursedDate`; for daily cadence, fees accrue every 24 hours and the `dueDate` is 7 days after `disbursedDate`. See [fee cadence and repayment timing](/circle-mint/concepts/credit-api#fee-cadence-and-repayment-timing) for the underlying model. If you supplied 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. ### 4.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](/circle-mint/concepts/credit-api#webhook-topics) for what each topic publishes. ## Step 5. Repay with crypto (the fast path) Call `POST /v1/credit/cryptoRepayment` with the amount you want to apply against the outstanding balance. The endpoint deducts USDC from your Circle Mint wallet at the time of the call. ```bash theme={null} curl -X POST https://api-sandbox.circle.com/v1/credit/cryptoRepayment \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "idempotencyKey": "d7a3e2c1-8f45-4b91-ae67-2c9d0f8b3e5a", "amount": { "amount": "50150.00", "currency": "USD" } }' ``` ```json theme={null} { "data": { "id": "e5f6a7b8-9012-3456-efab-345678901234", "amount": { "amount": "50150.00", "currency": "USD" }, "status": "pending", "createDate": "2024-03-25T10:00:00.000Z", "updateDate": "2024-03-25T10:00:00.000Z" } } ``` Repayment constraints to keep in mind: * The requested amount is capped at the outstanding balance across the credit line. A request that exceeds the cap returns HTTP 400. * Crypto repayment is Line of Credit only. Settlement Advance does not support this endpoint—see the [Settlement Advance quickstart](/circle-mint/quickstarts/settlement-advance) for SA repayment. ## Step 6. Repay with a wire (alternative) If you prefer fiat repayment, wire USD to Circle using the `wireInstructions` from Step 2. The `trackingRef` on the wire lets Circle match the payment to your credit line. In the sandbox, simulate the wire by posting a mock repayment: ```bash theme={null} curl -X POST https://api-sandbox.circle.com/v1/credit/mocks/repayments \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "fiatAccountId": "b8627ae8-732b-4d25-b947-1df8f4007a29", "amount": { "amount": "50150.00", "currency": "USD" } }' ``` ```json theme={null} { "data": { "trackingRef": "CIR3XBZZ4N", "amount": { "amount": "50150.00", "currency": "USD" }, "status": "pending" } } ``` ## 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 `status: completed`. The `type` is `crypto` for repayments from Step 5 or `fiat` for wire repayments from Step 6. Wire repayments initially return `status: pending` and transition to `completed` once Circle matches the inbound wire, so you may need to poll until settlement; the example below shows the final settled state. ```bash theme={null} curl "https://api-sandbox.circle.com/v1/credit/repayments?transferId=a1c2e3f4-5678-4d90-b123-456789abcdef" \ -H "Authorization: Bearer $API_KEY" ``` ```json theme={null} { "data": [ { "id": "d4e5f6a7-b890-1234-defa-234567890123", "transferId": "a1c2e3f4-5678-4d90-b123-456789abcdef", "amountApplied": { "amount": "50150.00", "currency": "USD" }, "paymentAmount": { "amount": "50150.00", "currency": "USD" }, "type": "crypto", "status": "completed", "settlementDate": "2024-03-25T10:00:00.000Z", "createDate": "2024-03-25T10:00:00.000Z", "updateDate": "2024-03-25T10:00:00.000Z" } ] } ``` `paymentAmount` is the total repayment received and `amountApplied` is the portion applied to this transfer's outstanding balance (principal plus fees). Crypto repayments omit `repaymentAccountId`; fiat repayments include it, set to the fiat account the wire was matched to. Then call `GET /v1/credit/transfers/{id}` again and confirm the transfer is `paid`. ```bash theme={null} curl https://api-sandbox.circle.com/v1/credit/transfers/a1c2e3f4-5678-4d90-b123-456789abcdef \ -H "Authorization: Bearer $API_KEY" ``` ```json theme={null} { "data": { "id": "a1c2e3f4-5678-4d90-b123-456789abcdef", "amount": { "amount": "50000.00", "currency": "USD" }, "status": "paid", "outstanding": { "amount": "0.00", "currency": "USD" }, "fees": { "total": { "amount": "150.00", "currency": "USD" }, "unpaid": { "amount": "0.00", "currency": "USD" } }, "dueDate": "2024-03-27T14:22:00.000Z", "paidDate": "2024-03-25T10:00:00.000Z", "disbursedDate": "2024-03-20T14:22:00.000Z", "createDate": "2024-03-20T14:20:00.000Z", "updateDate": "2024-03-25T10:00:00.000Z" } } ``` The transfer now shows `status: paid`, `outstanding` is zero, and `fees.unpaid` is zero—the draw lifecycle is complete.