METER → RATE → ORCHESTRATE → AUDIT

1. METER       Record a usage event (what happened, how much)
2. RATE        Apply pricing rules from the contract to get a cost
3. ORCHESTRATE Determine who gets paid, how much, in what order.
               Enforce policies. Signal external rail to execute.
               (Actual money movement: Stripe / Visa / ACH / stablecoin)
4. AUDIT       Write immutable record to the audit trail

curl https://api.umpledger.com/ump/v2/agents \
  -H "X-API-Key: ump_live_your_key_here"

{
  "error": "AUTHENTICATION_REQUIRED",
  "message": "Missing X-API-Key header. Get your key at https://umpledger.com/keys",
  "docs": "https://umpledger.com/keys"
}

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1709891234

npm install @umpledger/sdk

import { UMP } from '@umpledger/sdk';

const ump = new UMP({
  // Optional config — defaults work for alpha
});

import { UMP } from '@umpledger/sdk';
const ump = new UMP();

// Create an agent
const agent = ump.agents.create({
  name: 'Research Agent',
  type: 'AI_AGENT',
  capabilities: ['data.fetch'],
  authority: {
    maxPerTransaction: 100,
    maxPerDay: 5000,
  },
});

console.log(agent.agentId); // "agent_a1b2c3d4"

// Get an agent
const found = ump.agents.get('agent_a1b2c3d4');

// List agents
const allAgents = ump.agents.list({ status: 'ACTIVE' });

// Update authority
const updated = ump.agents.updateAuthority('agent_a1b2c3d4', {
  maxPerTransaction: 250,
});

// Verify an agent
const result = ump.agents.verify('agent_a1b2c3d4');
console.log(result.valid); // true

// Revoke (cascades to children)
const revoked = ump.agents.revoke('agent_a1b2c3d4');

import { UMP } from '@umpledger/sdk';
const ump = new UMP();

// Fund a wallet
const entry = ump.wallets.fund('wal_xyz', {
  amount: 10000,
  source: 'stripe_pm_abc',
  valueUnitType: 'USD_CENTS',
});

// Get balance
const balances = ump.wallets.getBalance('wal_xyz');
console.log(balances[0].available); // 10000

// Get ledger entries
const ledger = ump.wallets.getLedger('wal_xyz', 50, 0);

// Get wallet by agent
const wallet = ump.wallets.getByAgent('agent_abc');

// Freeze / Unfreeze
ump.wallets.freeze('wal_xyz');
ump.wallets.unfreeze('wal_xyz');

// Transfer between agents
ump.wallets.debit('wal_from', 100, 'agent_to', 'txn_ref');
ump.wallets.credit('wal_to', 100, 'agent_from', 'txn_ref');

import { UMP } from '@umpledger/sdk';
const ump = new UMP();

// High-level: meter + rate + orchestrate settlement in one call
const result = await ump.transact({
  from: 'agent_a1b2c3d4',
  to: 'agent_e5f6g7h8',
  service: 'data.fetch',
  payload: { tokens: 1200 },
  maxCost: 50,
});

console.log(result.transactionId); // "txn_..."
console.log(result.cost);          // 24
console.log(result.outcome);       // "SETTLED"

// Low-level: record usage event
const event = ump.metering.record({
  sourceAgentId: 'agent_a1b2c3d4',
  targetAgentId: 'agent_e5f6g7h8',
  serviceId: 'data.fetch',
  quantity: 1200,
  unit: 'tokens',
});

// Rate against a pricing rule
const ratingResult = ump.pricing.rate(rule, event);

import { UMP } from '@umpledger/sdk';
const ump = new UMP();

// Create a fixed contract
const contract = ump.contracts.create('agent_a1b2c3d4', {
  targetAgentId: 'agent_e5f6g7h8',
  mode: 'FIXED',
  pricingRules: [{
    serviceId: 'data.fetch',
    model: 'PER_UNIT',
    unit: 'tokens',
    pricePerUnit: 0.02,
    currency: 'USD_CENTS',
  }],
  effectiveUntil: new Date('2027-01-01'),
});

// Get a contract
const found = ump.contracts.get('ctr_xyz');

// Start negotiation
const proposal = ump.contracts.propose('agent_a1b2c3d4', {
  targetAgentId: 'agent_e5f6g7h8',
  pricingRules: [...],
});

// Accept / counter
ump.contracts.accept('ctr_xyz', 'agent_e5f6g7h8');
ump.contracts.counter('ctr_xyz', 'agent_e5f6g7h8', { pricingRules: [...] });

// Terminate
ump.contracts.terminate('ctr_xyz');

{
  "error": "INSUFFICIENT_FUNDS",
  "message": "Wallet wal_xyz has insufficient balance. Available: 10, Required: 50",
  "docs": "https://docs.umpledger.com"
}

git clone https://github.com/umpledger/ump-protocol.git
cd ump-protocol/ump-server
npm install

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "moduleResolution": "node",
    "declaration": true,
    "outDir": "./dist",
    "noEmitOnError": false,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

echo DATABASE_URL=postgresql://ump:ump_secure_2026@switchback.proxy.rlwy.net:44264/ump_db > .env
echo DATABASE_SSL=false >> .env
echo PORT=3000 >> .env

npx ts-node --transpile-only -r dotenv/config src/server.ts

[db] Running migrations...
[db] Migrations complete.
{"level":30,"msg":"Server listening at http://0.0.0.0:3000"}
{"level":30,"msg":"UMP server running on port 3000 with PostgreSQL storage"}

curl http://localhost:3000/health

{"status":"ok","version":"2.0.0-alpha.1","protocol":"UMP","storage":"postgresql"}

curl -X POST http://localhost:3000/ump/v2/agents   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"name": "Credit Check Agent", "agent_type": "AI_AGENT",
       "capabilities": ["credit-check", "bureau-query", "score-evaluation"],
       "authority": {"maxPerTransaction": 10, "maxPerDay": 1000}}'

curl -X POST http://localhost:3000/ump/v2/agents   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"name": "Fraud Risk Model Agent", "agent_type": "AI_AGENT",
       "capabilities": ["fraud-detection", "risk-scoring", "anomaly-detection"],
       "authority": {"maxPerTransaction": 10, "maxPerDay": 1000}}'

curl -X POST http://localhost:3000/ump/v2/agents   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"name": "Income AI Verification Agent", "agent_type": "AI_AGENT",
       "capabilities": ["income-verification", "document-analysis", "payroll-check"],
       "authority": {"maxPerTransaction": 10, "maxPerDay": 1000}}'

curl -X POST http://localhost:3000/ump/v2/agents   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"name": "Loan Pricing Engine Agent", "agent_type": "AI_AGENT",
       "capabilities": ["loan-pricing", "rate-calculation", "offer-generation"],
       "authority": {"maxPerTransaction": 50, "maxPerDay": 5000}}'

curl http://localhost:3000/ump/v2/agents   -H "X-API-Key: ump_sk_test_local"

curl -X POST http://localhost:3000/ump/v2/wallets/{wallet_id}/fund   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"amount": 100, "currency": "USD"}'

{"wallet_id":"wallet_...","balance":100,"currency":"USD","status":"ACTIVE"}

curl -X POST http://localhost:3000/ump/v2/contracts   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"source_agent_id": "agent_2fed540460cb4a5b",
       "target_agent_id": "agent_85d48935cc74407d",
       "service_name": "fraud-risk-check",
       "pricing_rules": [{"primitive": "FLAT_FEE", "amount": 5.00, "currency": "USD"}]}'

curl -X POST http://localhost:3000/ump/v2/contracts   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"source_agent_id": "agent_85d48935cc74407d",
       "target_agent_id": "agent_3c9b26070180457e",
       "service_name": "income-verification",
       "pricing_rules": [{"primitive": "FLAT_FEE", "amount": 5.00, "currency": "USD"}]}'

curl -X POST http://localhost:3000/ump/v2/contracts   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"source_agent_id": "agent_3c9b26070180457e",
       "target_agent_id": "agent_7204eeb4a2ce4aec",
       "service_name": "loan-pricing",
       "pricing_rules": [{"primitive": "FLAT_FEE", "amount": 5.00, "currency": "USD"}]}'

curl -X POST http://localhost:3000/ump/v2/transact   -H "X-API-Key: ump_sk_test_local"   -H "Content-Type: application/json"   -d '{"from": "agent_2fed540460cb4a5b",
       "to": "agent_85d48935cc74407d",
       "contract_id": "contract_88ecfd5b034e4542",
       "service": "fraud-risk-check",
       "payload": {"application_id": "loan_app_001"}}'

{
  "transaction_id": "txn_...",
  "cost": 5,
  "currency": "USD",
  "outcome": "COMPLETED",
  "audit_id": "audit_...",
  "settled_at": "2026-03-17T19:11:19.494Z",
  "duration_ms": 0
}

curl http://localhost:3000/ump/v2/audit   -H "X-API-Key: ump_sk_test_local"

curl "http://localhost:3000/ump/v2/audit?agent_id=agent_2fed540460cb4a5b"   -H "X-API-Key: ump_sk_test_local"

curl "http://localhost:3000/ump/v2/audit?operation=TRANSACTION_SETTLED"   -H "X-API-Key: ump_sk_test_local"

curl http://localhost:3000/ump/v2/wallets/{wallet_id}/balance   -H "X-API-Key: ump_sk_test_local"

curl -X POST http://localhost:3000/ump/v2/demo/reset   -H "X-API-Key: ump_sk_test_local"

{
  "mcpServers": {
    "ump": {
      "url": "https://ump-mcp-production.up.railway.app/mcp",
      "transport": "http",
      "headers": { "Authorization": "Bearer YOUR_UMP_KEY" }
    }
  }
}

{
  "ump": {
    "url": "https://ump-mcp-production.up.railway.app/mcp",
    "transport": "http",
    "headers": { "Authorization": "Bearer YOUR_UMP_KEY" }
  }
}

curl https://ump-mcp-production.up.railway.app/health

{
  "status": "ok",
  "name": "ump-mcp",
  "version": "1.0.0",
  "tools": 18,
  "transport": "streamable-http",
  "auth": "per-user Bearer token"
}