KALEDGE

Quickstart Guide

5 MINUTES

What You'll Build

In this guide, you'll create settlement receipts between two agents, batch them, and call the kernel to get a signed IAN (Inter-Agent Netting).

Step 1: Install the SDK

1 Install 
$ npm install @primordia1/sdk
$ pip install primordia-sdk

Step 2: Generate Agent Keys

2 Create Ed25519 Keypairs

Each agent needs a keypair for signing receipts.

import { generateKeyPair } from '@primordia/sdk';

// Generate keys for two agents
const agentA = generateKeyPair();
const agentB = generateKeyPair();

console.log('Agent A pubkey:', agentA.publicKey);
console.log('Agent B pubkey:', agentB.publicKey);
from primordia import generate_keypair

# Generate keys for two agents
agent_a = generate_keypair()
agent_b = generate_keypair()

print(f"Agent A pubkey: {agent_a.public_key}")
print(f"Agent B pubkey: {agent_b.public_key}")

Step 3: Create Settlement Receipts

3 Issue MSRs (Machine Settlement Receipts)

Create receipts when value is exchanged between agents.

import { createMSR } from '@primordia/sdk';

// Agent A pays Agent B $50 for compute
const receipt1 = createMSR({
  from_agent: agentA.publicKey,
  to_agent: agentB.publicKey,
  amount_micros: 50_000_000,  // $50 in micros
  currency: 'USD',
  resource_type: 'compute'
}, agentA.privateKey);

// Agent B pays Agent A $30 for data
const receipt2 = createMSR({
  from_agent: agentB.publicKey,
  to_agent: agentA.publicKey,
  amount_micros: 30_000_000,  // $30 in micros
  currency: 'USD',
  resource_type: 'data'
}, agentB.privateKey);

console.log('Created 2 receipts');
from primordia import create_msr

# Agent A pays Agent B $50 for compute
receipt1 = create_msr(
    from_agent=agent_a.public_key,
    to_agent=agent_b.public_key,
    amount_micros=50_000_000,  # $50 in micros
    currency="USD",
    resource_type="compute",
    private_key=agent_a.private_key
)

# Agent B pays Agent A $30 for data
receipt2 = create_msr(
    from_agent=agent_b.public_key,
    to_agent=agent_a.public_key,
    amount_micros=30_000_000,  # $30 in micros
    currency="USD",
    resource_type="data",
    private_key=agent_b.private_key
)

print("Created 2 receipts")
Note: Receipts are created locally and signed with Ed25519. No network call required. This is FREE.

Step 4: Verify Locally (Free)

4 Verify Signatures

Verify receipt signatures locally without calling the kernel.

import { verifyMSR } from '@primordia/sdk';

const isValid = verifyMSR(receipt1);
console.log('Receipt 1 valid:', isValid);  // true
from primordia import verify_msr

is_valid = verify_msr(receipt1)
print(f"Receipt 1 valid: {is_valid}")  # True

Step 5: Net Receipts (Paid)

5 Call the Kernel for Netting

Send receipts to the kernel to get a signed IAN with net obligations.

Paid Endpoint: This call requires an API key with credit balance. Fee: 5 bps on netted volume. 
const response = await fetch('https://clearing.kaledge.app/v1/net', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.KALEDGE_API_KEY
  },
  body: JSON.stringify({
    receipts: [receipt1, receipt2]
  })
});

const result = await response.json();

console.log('Net positions:', result.ian.net_positions);
// Output: Agent A owes Agent B $20 (net of $50 - $30)

console.log('Compression:', result.compression_ratio);
// Output: 0.25 (2 receipts compressed to 1 obligation)
import requests
import os

response = requests.post(
    "https://clearing.kaledge.app/v1/net",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["KALEDGE_API_KEY"]
    },
    json={
        "receipts": [receipt1, receipt2]
    }
)

result = response.json()

print(f"Net positions: {result['ian']['net_positions']}")
# Output: Agent A owes Agent B $20 (net of $50 - $30)

print(f"Compression: {result['compression_ratio']}")
# Output: 0.25 (2 receipts compressed to 1 obligation)
$ curl -X POST https://clearing.kaledge.app/v1/net \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $KALEDGE_API_KEY" \
    -d '{"receipts": [...]}'

You're Ready!

You've created receipts, verified them locally, and called the kernel for netting.

Full API Docs GitHub One Pager

Next Steps

Now that you understand the basics, explore these advanced features: