KALEDGE

API Documentation

Quickstart

https://clearing.kaledge.app

TypeScript

npm install @primordia1/sdk

Python

pip install primordia-sdk

// Create and verify a settlement receipt
import { createMSR, verifyMSR } from '@primordia/sdk';

const receipt = createMSR({
  from_agent: 'agent_a_pubkey',
  to_agent: 'agent_b_pubkey',
  amount_micros: 50_000_000,  // $50
  currency: 'USD'
});

// Verify locally (FREE)
const valid = verifyMSR(receipt);

// Net with kernel (PAID - 5 bps)
const ian = await fetch('https://clearing.kaledge.app/v1/net', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.PRIMORDIA_KEY },
  body: JSON.stringify({ receipts: [receipt] })
});

Authentication

Free endpoints require no authentication. Paid endpoints require an API key via X-API-Key header, linked to a credit balance.

# Request with API key
curl -X POST https://clearing.kaledge.app/v1/net \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -d '{"receipts": [...]}'

Free Tier Endpoints

GET /healthz FREE

Health check. Returns kernel status and public key.

// Response
{
  "status": "ok",
  "database": "connected",
  "timestamp": 1704067200000,
  "kernel_pubkey": "a5e88c3c..."
}

GET /v1/spec FREE

Returns the canonical Kaledge specification (JSON schemas for all primitives).

POST /v1/verify FREE

Verify any Kaledge primitive (MSR, IAN, FC, MBS). Rate limited: 100 req/min.

// Request
{
  "type": "msr",
  "data": { /* MSR object */ }
}

// Response
{
  "valid": true,
  "signature_valid": true,
  "hash": "blake3_hash..."
}

POST /v1/seal/verify FREE

Verify a Kaledge Seal (conformance stamp issued by kernel).

Settlement Endpoints

POST /v1/net 5 BPS

Net multiple receipts into minimal obligations. Returns kernel-signed IAN.

// Request
{
  "receipts": [
    { /* MSR 1 */ },
    { /* MSR 2 */ },
    { /* MSR 3 */ }
  ],
  "algorithm": "multilateral"  // or "bilateral", "novation"
}

// Response
{
  "ian": {
    "version": "0.1",
    "net_positions": [...],
    "kernel_signature": "ed25519_sig..."
  },
  "fee_micros": 25000,
  "compression_ratio": 0.15
}

200 IAN created and signed

402 Insufficient credit - BOOKS OPEN

400 Invalid receipts or signatures

POST /v1/net/batch 5 BPS

Batch netting for high-volume clients. Up to 10,000 receipts per call.

POST /v1/mbs PAID

Submit a Machine Balance Sheet for an agent. Required for credit line approval.

Credit Endpoints

POST /v1/credit/packs FREE

List available credit packs.

// Response
{
  "packs": [
    { "id": "pack_100k", "credits": 100000, "price_cents": 10000000 },
    { "id": "pack_250k", "credits": 250000, "price_cents": 24500000 },
    { "id": "pack_1m", "credits": 1000000, "price_cents": 95000000 }
  ]
}

POST /v1/credit/create_intent PAID

Create a Stripe checkout session to purchase a credit pack.

GET /v1/credit/balance PAID

Get current credit balance for API key.

POST /v1/credit/line/open 200 BPS

Open a credit line for an agent. Requires MBS submission and approval.

// Request
{
  "agent_id": "agent_pubkey",
  "requested_limit_micros": 10000000000,  // $10,000
  "mbs_hash": "blake3_hash_of_submitted_mbs"
}

// Response
{
  "line_id": "line_xxxxxxxx",
  "approved_limit_micros": 5000000000,
  "spread_bps": 200,
  "status": "active"
}

POST /v1/credit/draw 200 BPS

Draw from an open credit line.

POST /v1/credit/repay PAID

Repay drawn credit.

POST /v1/default/trigger PAID

Trigger a default event for an agent that has failed to meet obligations.

POST /v1/default/resolve $25,000

Resolve a default. Executes waterfall distribution to creditors.

Primitives Reference

Primitive	Name	Description
`MSR`	Machine Settlement Receipt	Immutable proof of value exchange between agents
`IAN`	Inter-Agent Netting	Compressed net obligations from N receipts
`FC`	Future Commitment	Binding forward obligation with conditions
`MBS`	Machine Balance Sheet	Agent economic snapshot (assets, liabilities, equity)
`DBP`	Default/Bankruptcy Primitive	Deterministic insolvency resolution
`VAS`	Verifiable Agent State	Merkle-tree-based state snapshot
`STP`	State Transition Proof	Cryptographic proof of state change
`AMR`	Attested Meter Receipt	Resource consumption proof
`CMR`	Compute Meter Receipt	GPU/CPU usage attestation

SDKs & Tools

TypeScript SDK

npm install @primordia1/sdk

Python SDK

pip install primordia-sdk

Runtime Hook (TS)

npm install @primordia/runtime-hook

Runtime Hook (PY)

pip install primordia-runtime-hook

MCP Server

npm install @primordia1/mcp-server

Conformance Tests

github.com/primordia-ai/primordia

Error Codes

// 402 - Payment Required (BOOKS OPEN)
{
  "error": "insufficient_credit",
  "message": "BOOKS OPEN - Purchase credit pack to continue",
  "balance_micros": 0,
  "required_micros": 25000,
  "packs_url": "/v1/credit/packs"
}

// 400 - Bad Request
{
  "error": "invalid_signature",
  "message": "MSR signature verification failed",
  "field": "receipts[0].signature"
}

// 401 - Unauthorized
{
  "error": "invalid_api_key",
  "message": "API key not found or revoked"
}