Quickstart: Draw and Repay a Line of Credit

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 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. 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.

Step 1. Check the credit line

Call GET /v1/credit to confirm your credit line is active and has sufficient capacity for the draw.

curl https://api-sandbox.circle.com/v1/credit \
  -H "Authorization: Bearer $API_KEY"

{
  "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.

curl https://api-sandbox.circle.com/v1/credit/repaymentAccounts/b8627ae8-732b-4d25-b947-1df8f4007a29 \
  -H "Authorization: Bearer $API_KEY"

{
  "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.

Sandbox mock repayment example

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" }
  }'

{
  "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.

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"
    }
  }'

{
  "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.

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.

curl https://api-sandbox.circle.com/v1/credit/transfers/a1c2e3f4-5678-4d90-b123-456789abcdef \
  -H "Authorization: Bearer $API_KEY"

{
  "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 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. 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 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.

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" }
  }'

{
  "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 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:

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" }
  }'

{
  "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.

curl "https://api-sandbox.circle.com/v1/credit/repayments?transferId=a1c2e3f4-5678-4d90-b123-456789abcdef" \
  -H "Authorization: Bearer $API_KEY"

{
  "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). Then call GET /v1/credit/transfers/{id} again and confirm the transfer is paid.

curl https://api-sandbox.circle.com/v1/credit/transfers/a1c2e3f4-5678-4d90-b123-456789abcdef \
  -H "Authorization: Bearer $API_KEY"

{
  "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.

Documentation Index

​Prerequisites

​Step 1. Check the credit line

​Step 2. Get wire repayment instructions (optional fallback)

​Step 3. Request a draw

​Step 4. Observe disbursement and fee accrual

​4.1. Poll the transfer

​4.2. Subscribe to webhooks

​Step 5. Repay with crypto (the fast path)

​Step 6. Repay with a wire (alternative)

​Step 7. Confirm the repayment