Monitor collateral and handle a margin warning

Read collateral health; on a floor breach CLC raises a ladder margin warning. Cure by repaying (or the borrower adds collateral) before the deadline, or it escalates to margin call.

Scope facility:read

Prerequisites: Facility is APPROVED

1. Read collateral + health

curl -X GET https://api.clc.solutions/v1/facilities/fac_7a1b/collateral \
  -H "X-CLC-Key-Id: $CLC_KEY_ID" \
  -H "X-CLC-Timestamp: $CLC_TIMESTAMP" \
  -H "X-CLC-Signature: $CLC_SIGNATURE"

{
  "positions": [
    {
      "asset": "BTC",
      "quantity": "0.5"
    },
    {
      "asset": "ETH",
      "quantity": "3.0"
    }
  ],
  "collateral_value_usd": "66927.00",
  "required_floor_usd": "40000.00",
  "ltv": "0.62",
  "health": "HEALTHY"
}

2. Margin warning raised (CLC-internal)

CLC-internal, delivered to your webhook endpoint.

← margin_warning.raised  (CLC posts this to your webhook URL)

{
  "type": "margin_warning.raised",
  "data": {
    "facility_id": "fac_7a1b",
    "number": 3,
    "tier": 1,
    "cure_amount": {
      "amount": "6000.00",
      "asset": "USD"
    },
    "deadline": "2026-07-22T14:00:00Z"
  }
}

3. Fetch a margin warning

facility_id + number is the key, the same shape a margin call uses. number is the warning's position on that facility, from 1 — and it counts warnings, so warning 3 has nothing to do with margin call 3 on the same facility.

curl -X GET https://api.clc.solutions/v1/facilities/fac_7a1b/margin-warnings/3 \
  -H "X-CLC-Key-Id: $CLC_KEY_ID" \
  -H "X-CLC-Timestamp: $CLC_TIMESTAMP" \
  -H "X-CLC-Signature: $CLC_SIGNATURE"

{
  "facility_id": "fac_7a1b",
  "number": 3,
  "tier": 1,
  "status": "OPEN",
  "cure_amount_usd": "6000.00",
  "cure_deadline": "2026-07-22T14:00:00Z",
  "ltv_at_raise": "0.71",
  "raised_at": "2026-07-22T10:00:00Z"
}

A warning carries a deadline, so a delivery that was missed or arrived late is worse here than anywhere else — the borrower is racing a clock they cannot see. Read it back rather than reconstructing it from the webhook you did get.

4. Cure the margin warning

Cure by repaying, or the borrower deposits more collateral into their custody account, which raises collateral_value_usd and can clear the floor without any money reaching CLC.

curl -X POST https://api.clc.solutions/v1/facilities/fac_7a1b/repayments \
  -H "X-CLC-Key-Id: $CLC_KEY_ID" \
  -H "X-CLC-Timestamp: $CLC_TIMESTAMP" \
  -H "X-CLC-Signature: $CLC_SIGNATURE" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "margin_warning_number": 3,
    "amount": "6000.00",
    "asset": "USDC"
  }'

{
  "id": "rep_9a2",
  "facility_id": "fac_7a1b",
  "margin_warning_number": 3,
  "status": "PENDING",
  "amount": "6000.00",
  "asset": "USDC",
  "instructions": [
    {
      "operation": "transfer",
      "source": "borrower",
      "destination": "clc",
      "amount": "6000.00",
      "asset": "USDC"
    }
  ],
  "requested_at": "2026-07-22T09:15:00Z"
}

Send margin_warning_number whenever the repayment is a cure. CLC can guess — a repayment landing while a warning is open is probably the cure — but a borrower who repays for their own reasons during that window makes the guess wrong, and the guess is what decides whether the deadline was met.

The repayment comes back with instructions, the same as any other. Execute them in order and report it against the repayment:

curl -X POST https://api.clc.solutions/v1/facilities/fac_7a1b/repayments/rep_9a2/execution \
  -H "X-CLC-Key-Id: $CLC_KEY_ID" \
  -H "X-CLC-Timestamp: $CLC_TIMESTAMP" \
  -H "X-CLC-Signature: $CLC_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "status": "completed",
    "delivered": {
      "amount": "6000.00",
      "asset": "USDC"
    },
    "reference": "0x3d7e40cc"
  }'

There is no execution report on the warning itself. The cure is the repayment, and the repayment already carries the instructions and takes the report. A second report on the warning would be the same money movement described twice, and two records of one event to reconcile. Curing by depositing collateral needs no report at all — nothing was instructed; the portfolio push is what tells CLC.

When the balance clears the floor, margin_warning.cured fires. If the deadline passes first, margin_warning.escalated does, and the margin call takes over.