Clearing Rail

Settlement and clearing operations endpoints.

Overview

The Clearing rail provides:

Payment clearing
Settlement processing
Netting calculations
Reconciliation

Endpoints

Create Clearing

POST /v1/clearing/instructions

const clearing = await iof.clearing.create({
  type: "payment",
  amount: 50000,
  currency: "USD",
  sender: { account: "acc_123" },
  receiver: { account: "acc_456" },
  valueDate: "2024-01-16",
});

Response:

{
  "id": "clr_abc",
  "status": "pending",
  "type": "payment",
  "amount": 50000,
  "currency": "USD",
  "valueDate": "2024-01-16",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Clearing

GET /v1/clearing/instructions/:id

const clearing = await iof.clearing.get("clr_abc");

List Clearings

GET /v1/clearing/instructions

const clearings = await iof.clearing.list({
  status: "pending",
  valueDate: "2024-01-16",
  limit: 50,
});

Calculate Netting

POST /v1/clearing/netting

const netting = await iof.clearing.calculateNetting({
  participants: ["party_a", "party_b", "party_c"],
  date: "2024-01-15",
});

Response:

{
  "netPositions": [
    { "participant": "party_a", "net": 25000, "direction": "receive" },
    { "participant": "party_b", "net": -15000, "direction": "pay" },
    { "participant": "party_c", "net": -10000, "direction": "pay" }
  ],
  "grossVolume": 150000,
  "netVolume": 50000,
  "nettingEfficiency": 0.67
}

Settle

POST /v1/clearing/settle

const settlement = await iof.clearing.settle({
  clearingIds: ["clr_abc", "clr_def"],
  method: "rtgs",
});

Settlement Cycles

Cycle	Description
`T+0`	Same-day settlement
`T+1`	Next business day
`T+2`	Two business days
`T+3`	Three business days

Status

Status	Description
`pending`	Awaiting processing
`matched`	Instructions matched
`settling`	Settlement in progress
`settled`	Successfully settled
`failed`	Settlement failed

Webhooks

Event	Description
`clearing.created`	Instruction created
`clearing.matched`	Instructions matched
`clearing.settled`	Settlement completed
`clearing.failed`	Settlement failed

Next Steps

Ledger Rail - Accounting entries
Treasury Rail - Position management