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 → 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

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

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"
}

MCP Server

The UMP MCP server lets any Model Context Protocol client — Claude Desktop, Cursor, VS Code Copilot, or your own agent — manage UMP agents, wallets, transactions, and contracts conversationally. No extra code. Just connect and ask.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools and services. The UMP MCP server implements MCP's Streamable HTTP transport, so any MCP-compatible client can interact with the entire UMP API surface by simply describing what they want in natural language.

Quick Connect

Add the following to your MCP client config:

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

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

{
  "mcp.servers": {
    "ump": {
      "url": "https://ump-mcp-production.up.railway.app/mcp",
      "transport": "http"
    }
  }
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-app", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(
  new URL("https://ump-mcp-production.up.railway.app/mcp")
);
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();

// Call a tool
const result = await client.callTool({
  name: "ump_register_agent",
  arguments: {
    name: "my-agent",
    type: "AI_AGENT",
    max_per_transaction: 10,
    max_per_day: 100,
  }
});

Environment Variables

The MCP server reads its UMP API key from the UMP_API_KEY environment variable set on the Railway service. If you are self-hosting, set this variable before starting:

UMP_API_KEY=ump_sk_your_key_here npm start

Available Tools

The server exposes 18 tools across 4 categories. All tool call results are formatted as JSON.

🤖 Agent Management

💳 Wallet Operations

⚡ Transactions

📄 Contracts & Pricing

Example Prompts

Once connected, you can ask your AI assistant things like:

"Register a new AI agent called billing-bot with a $5 per-transaction limit and $200/day cap"

"Fund wallet_8d4b1ef3 with $100"

"Create a TIERED pricing contract between agent_abc and agent_xyz for the text-generation service:
  first 10,000 tokens at $0.002, everything above at $0.001"

"Execute a transaction from agent_abc to agent_xyz for the code-review service, max $3"

"Show me the audit trail for agent_abc for the past 48 hours"

"Simulate what UNIT_RATE pricing of $0.0005/token costs for 1 million tokens"

Self-Hosting

The MCP server is open source in the ump-mcp directory of the UMP Protocol repo. To run locally:

git clone https://github.com/umpledger/ump-protocol.git
cd ump-protocol/ump-mcp
npm install
UMP_API_KEY=ump_sk_your_key npm run dev
# Server running at http://localhost:3001/mcp

Transport Details

The server uses the MCP Streamable HTTP transport in stateless mode — every request creates a fresh server instance with no shared session state. This is ideal for serverless and cloud deployments and means you can horizontally scale the MCP server without any coordination overhead.

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