Quickstart

Get an agent transacting in under 5 minutes. This guide walks through creating two agents, funding one, and executing a transaction between them.

# Create the payer agent
curl -X POST https://api.umpledger.com/ump/v2/agents \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Agent",
    "type": "AI_AGENT",
    "capabilities": ["data.fetch", "analysis"],
    "authority": {
      "max_per_transaction": 100,
      "max_per_day": 1000
    }
  }'

# Response: { "agent_id": "agent_abc123", "wallet_id": "wal_xyz789", ... }

# Create the payee (service provider) agent
curl -X POST https://api.umpledger.com/ump/v2/agents \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Provider Agent",
    "type": "AI_AGENT",
    "capabilities": ["data.serve"]
  }'

# Response: { "agent_id": "agent_def456", "wallet_id": "wal_uvw321", ... }

curl -X POST https://api.umpledger.com/ump/v2/wallets/wal_xyz789/fund \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "source": "stripe_pm_abc",
    "value_unit_type": "USD_CENTS"
  }'

# Response: { "entry_id": "lge_...", "balance_after": 500 }

curl -X POST https://api.umpledger.com/ump/v2/transact \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "agent_abc123",
    "to": "agent_def456",
    "service": "data.fetch",
    "payload": { "query": "market data Q1 2026", "tokens": 1200 },
    "max_cost": 50
  }'

{
  "transaction_id": "txn_a1b2c3d4",
  "cost": 24,
  "currency": "USD_CENTS",
  "outcome": "SETTLED",
  "audit_id": "aud_e5f6g7h8",
  "settled_at": "2026-03-08T09:33:24.915Z",
  "duration_ms": 42
}

curl https://api.umpledger.com/ump/v2/wallets/wal_xyz789/balance \
  -H "X-API-Key: YOUR_KEY"

# { "wallet_id": "wal_xyz789", "balances": [{ "available": 476, ... }] }

Concepts

Understanding the UMP model before you build will save a lot of time. Here's how the pieces fit together.

Agent Identity

Every participant in the UMP network is an Agent — an AI model, a microservice, a bot, or even a human-facing application. Agents have:

• Agent ID — globally unique identifier (agent_*)
• Type — AI_AGENT, HUMAN_DELEGATE, or SYSTEM
• Capabilities — what services the agent can provide or consume
• Authority Scope — spending limits enforced by the protocol
• Parent/Child hierarchy — agents can spawn sub-agents with restricted authority

Wallets

Every agent automatically gets a Wallet when created. Wallets hold balances in multiple value unit types (USD, tokens, credits). Key operations:

• Fund — top up from an external payment source
• Debit/Credit — happens automatically during settlement
• Freeze/Unfreeze — emergency controls
• Ledger — immutable record of every balance change

Contracts

A Contract governs how two agents transact. It defines pricing rules, validity periods, and negotiation terms. Contracts can be:

• FIXED — one party sets terms, other accepts
• DYNAMIC — back-and-forth negotiation (propose → counter → accept)
• SPOT — no contract, use default rates

The Transaction Lifecycle

A UMP transaction goes through four stages:

METER → RATE → SETTLE → AUDIT

1. METER    Record a usage event (what happened, how much)
2. RATE     Apply pricing rules from the contract to get a cost
3. SETTLE   Debit payer wallet, credit payee wallet atomically
4. AUDIT    Write immutable record to the audit trail

The POST /transact endpoint runs all four stages in one call. For advanced use cases, you can call each stage individually.

Pricing Rules

Pricing rules define how usage is billed. Supported models:

• PER_UNIT — fixed price per unit (e.g., $0.01 per token)
• TIERED — price breaks at volume thresholds
• PERCENTAGE — take a % of a declared value
• FLAT_FEE — fixed fee per call regardless of usage

Authority Scopes

Authentication

All UMP API requests are authenticated with an API key passed as a request header.

API Key Header

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

Unauthenticated response

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

Rate Limits

The API allows 1,000 requests per minute per API key. Rate limit headers are returned on every response:

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

Public endpoints

The following endpoint does not require authentication:

• GET /health — server health check

Agents

Agents are the primary actors in the UMP network. Every agent has an identity, capabilities, spending limits, and an associated wallet.

curl -X POST https://api.umpledger.com/ump/v2/agents \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Agent",
    "type": "AI_AGENT",
    "capabilities": ["data.fetch", "analysis.run"],
    "authority": {
      "max_per_transaction": 100,
      "max_per_day": 5000,
      "max_per_month": 50000
    }
  }'

{
  "agent_id": "agent_a1b2c3d4",
  "agent_type": "AI_AGENT",
  "display_name": "Research Agent",
  "parent_id": null,
  "capabilities": ["data.fetch", "analysis.run"],
  "authority_scope": {
    "max_per_transaction": 100,
    "max_per_day": 5000,
    "max_per_month": 50000,
    "allowed_services": null,
    "allowed_counterparties": null
  },
  "wallet_id": "wal_e5f6g7h8",
  "status": "ACTIVE",
  "created_at": "2026-03-08T09:33:24.915Z"
}

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

curl "https://api.umpledger.com/ump/v2/agents?status=ACTIVE" \
  -H "X-API-Key: YOUR_KEY"

curl -X PATCH https://api.umpledger.com/ump/v2/agents/agent_a1b2c3d4/authority \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "max_per_transaction": 250, "max_per_day": 10000 }'

curl -X POST https://api.umpledger.com/ump/v2/agents/agent_a1b2c3d4/verify \
  -H "X-API-Key: YOUR_KEY"

{ "agent_id": "agent_a1b2c3d4", "valid": true, "reason": null, "verified_at": "2026-03-08T..." }

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

{ "revoked_agents": ["agent_a1b2c3d4", "agent_child1"], "count": 2 }

Wallets

Every agent has a wallet. Wallets hold balances, track every transaction in a ledger, and can be frozen for emergency control.

curl -X POST https://api.umpledger.com/ump/v2/wallets/wal_e5f6g7h8/fund \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "source": "stripe_pm_abc123", "value_unit_type": "USD_CENTS" }'

curl https://api.umpledger.com/ump/v2/wallets/wal_e5f6g7h8/balance \
  -H "X-API-Key: YOUR_KEY"

{
  "wallet_id": "wal_e5f6g7h8",
  "frozen": false,
  "balances": [{
    "value_unit_type": "USD_CENTS",
    "currency": "USD",
    "amount": 10000,
    "reserved": 0,
    "available": 10000
  }]
}

Transactions

Execute value transfers between agents. Use the high-level /transact endpoint for most cases, or call each pipeline stage individually for advanced control.

curl -X POST https://api.umpledger.com/ump/v2/transact \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "agent_a1b2c3d4",
    "to": "agent_e5f6g7h8",
    "service": "data.fetch",
    "payload": { "tokens": 1200 },
    "max_cost": 50
  }'

{
  "transaction_id": "txn_a1b2c3d4",
  "cost": 24,
  "currency": "USD_CENTS",
  "outcome": "SETTLED",
  "audit_id": "aud_e5f6g7h8",
  "settled_at": "2026-03-08T09:33:24.915Z",
  "duration_ms": 42
}

curl -X POST https://api.umpledger.com/ump/v2/usage-events \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "source_agent_id": "agent_a1b2c3d4",
      "target_agent_id": "agent_e5f6g7h8",
      "service_id": "llm.inference",
      "quantity": 4200,
      "unit": "tokens",
      "contract_id": "ctr_xyz"
    }
  ]'

curl https://api.umpledger.com/ump/v2/transactions/txn_a1b2c3d4 \
  -H "X-API-Key: YOUR_KEY"

Contracts

Contracts define the pricing rules between two agents. Without a contract, UMP uses default spot rates. With a contract, you get explicit pricing, validity windows, and negotiation flows.

curl -X POST https://api.umpledger.com/ump/v2/contracts \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_agent_id": "agent_a1b2c3d4",
    "target_agent_id": "agent_e5f6g7h8",
    "mode": "FIXED",
    "pricing_rules": [{
      "service_id": "data.fetch",
      "model": "PER_UNIT",
      "unit": "tokens",
      "price_per_unit": 0.02,
      "currency": "USD_CENTS"
    }],
    "effective_until": "2027-01-01T00:00:00Z"
  }'

curl https://api.umpledger.com/ump/v2/contracts/ctr_xyz \
  -H "X-API-Key: YOUR_KEY"

Audit Trail

Every transaction automatically creates an immutable audit record. Query audit logs for compliance, debugging, and dispute resolution.

curl https://api.umpledger.com/ump/v2/audit/aud_e5f6g7h8 \
  -H "X-API-Key: YOUR_KEY"

{
  "audit_id": "aud_e5f6g7h8",
  "transaction_id": "txn_a1b2c3d4",
  "from_agent": "agent_a1b2c3d4",
  "to_agent": "agent_e5f6g7h8",
  "service": "data.fetch",
  "amount": 24,
  "currency": "USD_CENTS",
  "outcome": "SETTLED",
  "timestamp": "2026-03-08T09:33:24.915Z",
  "immutable": true
}

SDK Installation

The @umpledger/sdk package lets you embed UMP directly in your Node.js or TypeScript application — no HTTP calls needed.

Install

npm install @umpledger/sdk

Initialize

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

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

Requirements

• Node.js 18+
• TypeScript 5+ (optional but recommended)

SDK — Agents

Manage agent identities programmatically using the SDK.

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');

SDK — Wallets

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');

SDK — Transactions

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

// High-level: meter + rate + settle 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);

SDK — Contracts

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 Reference

UMP API errors always return a JSON body with error and message fields.

Error response format

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

Changelog

v2.0.0-alpha.1 — March 2026

Initial public alpha release.

• Agent identity management (create, list, verify, revoke)
• Wallet system with fund, balance, ledger, freeze/unfreeze, transfer
• Full transaction pipeline: /transact, /usage-events, /rate, /settle
• Contract management with fixed, dynamic, and spot modes
• Immutable audit trail
• Dispute submission and tracking
• @umpledger/sdk npm package
• Live API at api.umpledger.com