run.pay Documentation

Quickstart — Agent Developer

The fastest path from zero to a paid API call.

pip install runpay          # Python
npm install runpay        # JavaScript

curl -X POST https://runpay-backend-visibility-production.up.railway.app/api/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "My Agent"}'

import runpay

runpay.configure(agent_id="agt_abc123def456")

result = runpay.call("halludetect", {
    "response": "According to Einstein, E=mc² was published in 2003"
})

print(result["hallucination_score"])  # 0-100

Authentication

The SDK sends your agent ID as a header automatically (runpay.configure() handles this). If you're calling the API directly instead of using the SDK, the exact mechanism depends on the endpoint:

X-RunPay-Agent: agt_your_agent_id

{ "agent_id": "agt_your_agent_id", "payload": { ... } }

Base URL

All API requests go to:

https://runpay-backend-visibility-production.up.railway.app

No versioning prefix yet — all endpoints shown in this documentation are relative to this base URL.

Create Agent Wallet

Two ways to get a wallet, depending on whether a human is involved in the setup:

Call a Service

curl -X POST https://runpay-backend-visibility-production.up.railway.app/api/call/14783c94-915e-4054-83eb-af6b22c542c3 \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_your_agent",
    "payload": {
      "response": "The Eiffel Tower was built in 1850 according to French records."
    }
  }'

Workflows

A vendor can publish a multi-step pipeline as one purchasable unit — call the whole chain in a single request. Billed step-by-step: if a step fails partway through, you're only ever charged for the steps that genuinely succeeded, never the ones that didn't run.

curl -X POST https://runpay-backend-visibility-production.up.railway.app/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wf-exec-a1b2c3" \
  -d '{
    "agent_id": "agt_your_agent",
    "input": {
      "text": "The document to process"
    }
  }'

Leaderboard

Real, verified rankings — every badge requires a genuine minimum sample size and diverse usage across distinct agents. None can be earned from a single call or a handful of self-generated ones.

External Discovery

run.pay aggregates three independent x402 ecosystems alongside its own catalog — the Coinbase x402 Bazaar, Circle's Agent Marketplace, and agent402.tools. Search once, see everything.

Native Crypto Payment (x402)

run.pay accepts native crypto payment (USDC on Base) directly, alongside Stripe — no account, no API key, no wallet setup on our side needed by the buyer. Standard x402 protocol, scheme exact, verified and settled by run.pay itself, no third-party facilitator dependency. Confirmed working end-to-end with real, verifiable on-chain settlement across multiple services.

Machine Payments Protocol (MPP)

Stripe and Tempo's open standard for agent payments — a real, third native payment path alongside Stripe checkout and x402 crypto. Runs entirely on run.pay's existing Stripe infrastructure; no new dependency. Minimum $0.50 per charge — a real card network rule, not a run.pay restriction.

UCP Discoverability

run.pay publishes a standard Universal Commerce Protocol manifest so UCP-aware agents can discover it without hard-coded integration.

Agent Economic Layer

Beyond calling services, agents can transact directly with each other. All routes are POST to /internal/{name} with an X-RunPay-Agent header and an action field selecting the operation.

Spending Mandates (AP2-inspired)

A real human can cryptographically pre-authorize what an agent may spend, before any call happens — reusing the same EIP-712 signature infrastructure as native crypto payment.

Guard (Risk Engine)

A real, unified decision engine — combines trust score, active mandate limits, and the human approval threshold into one coherent verdict. Read-only: it never commits a spend itself, real enforcement still happens at actual payment time.

Intent Firewall

Distinct from Guard: Guard asks "can this agent spend this amount?" — Intent Firewall asks "is this actually what the agent said it was going to do?" A real, direct mitigation against prompt-injection and context-manipulation risks in agentic payment flows.

Multi-Rail Router

Recommends the real best payment rail among those actually built and working — x402 crypto, MPP, Stripe, and now XRPL.

Agent Passport

A real aggregation, never a new source of truth — pulls identity verification, wallet status, reputation, active mandate, and recent activity into one unified view.

Accounting

Real spending broken down by service category — reuses the existing hierarchical wallet system for a genuine fleet-wide view when an agent has children.

Treasury

A real enrichment of the hierarchical wallet system — group child agents into departments for cost-center-style aggregation.

Financial Dashboard

A real fleet-wide summary — total agents, balance, today's spend, transaction count, failure rate, pending approvals.

Observability

Connects the Intent Firewall to the real transaction it resulted in — a complete, real audit chain: declared intent → vendor selected → price → payment status.

Economic Chains

A real, hash-chained ledger for multi-hop agent-to-agent workflows — genuinely a ledger, never an auto-executing orchestrator. Each agent reports its own real payment, already made separately through the normal payment routes.

Smart Ranking

An honestly-documented composite ranking — never an opaque score. Add sort=smart to /api/services/catalog.

Kill Switch

A real, three-level emergency freeze — platform-wide, per-agent, or per-vendor — checked before every real payment across x402, native crypto, MPP, and XRPL.

SDK Reference

Python

import runpay

runpay.configure(agent_id="agt_your_agent")

# Call any service by ID
result = runpay.call("halludetect", {"response": "..."})

# List available services
services = runpay.services(category="AI")

# Check wallet balance
balance = runpay.wallet()

JavaScript

const { configure, call, services, wallet } = require('runpay')
// or: import { configure, call, services, wallet } from 'runpay'

configure('agt_your_agent')

// Call any service by ID
const result = await call('halludetect', { response: '...' })

// List available services
const allServices = await services('AI')

// Check wallet balance
const balance = await wallet()

Framework Guides

LangChain

Generate all 205 services as ready-to-use LangChain tools in one line — no manual wrapping needed:

from runpay.langchain import get_tools

tools = get_tools(agent_id="agt_your_agent")                      # all your available services
tools = get_tools(agent_id="agt_your_agent", category="Security")  # just one category

from langchain.agents import initialize_agent
agent = initialize_agent(tools, llm, agent="zero-shot-react-description")

CrewAI

Same idea — generated automatically from the live catalog:

from runpay.crewai import get_tools

tools = get_tools(agent_id="agt_your_agent")

from crewai import Agent
researcher = Agent(role="Researcher", goal="...", tools=tools)

AutoGen

No dedicated integration yet — wrap the function you need directly:

import autogen
import runpay

runpay.configure(agent_id="agt_your_agent")

def check_hallucination(response: str) -> dict:
    """Check if an LLM response contains hallucinations."""
    return runpay.call("halludetect", {"response": response})

assistant = autogen.AssistantAgent(
    name="assistant",
    llm_config={
        "functions": [{
            "name": "check_hallucination",
            "description": "Check LLM output for hallucination risk",
            "parameters": {"type": "object", "properties": {"response": {"type": "string"}}}
        }]
    }
)
autogen.register_function(check_hallucination, caller=assistant)

Error Handling

import runpay
from runpay import RunpayError, InsufficientBalanceError

try:
    result = runpay.call("halludetect", payload)
except InsufficientBalanceError as e:
    print(f"Need ${e.required}, have ${e.balance}")
    add_funds_to_wallet()
except RunpayError as e:
    print(f"Call failed: {e}")

Publishing a Service (Providers)

Publish your API on run.pay and every AI agent developer becomes a potential customer. You keep 98% of every call.

curl -X POST .../api/vendors/register \
  -d '{"email": "you@company.com", "name": "My Service"}'

# Returns: {"vendor_id": "...", "api_key": "vnd_xxxxxxxxxx", "stripe_onboarding_url": "..."}

curl -X POST .../api/services \
  -H "x-api-key: vnd_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Web Scraper",
    "description": "Scrape any URL, returns clean markdown",
    "price_per_call": 0.05,
    "endpoint_url": "https://api.yoursite.com/scrape",
    "category": "DATA",
    "schema_input": {
      "url": "URL to scrape"
    }
  }'

Pricing Guide

You set your own price per call — run.pay takes a flat 2% commission, no subscription, no listing fee. Payouts go to your connected Stripe account.

Analytics

Your vendor dashboard shows live revenue, calls per service, error rates, and a breakdown by agent — no separate analytics API needed for normal use. If you're building your own reporting, the same data is available at GET /api/vendors/stats and GET /api/vendors/analytics (both require your x-api-key header).

Webhook Format

When an agent calls your service, run.pay forwards the agent's payload directly to your endpoint — no wrapper object, just the raw payload the agent sent:

POST https://api.yoursite.com/your-endpoint
Content-Type: application/json
X-RunPay-Call-Id: 1735689600.a1b2c3d4e5f6...
X-RunPay-Agent: agt_caller_agent
X-RunPay-Protocol: x402
X-RunPay-Signature: sha256=...

{ ...agent's raw input, exactly as they sent it... }

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', SIGNING_SECRET)
  .update(rawRequestBody).digest('hex');
if (expected !== req.headers['x-runpay-signature']) {
  return res.status(401).json({ error: 'Invalid signature' });
}

API Reference — List Services

API Reference — Call Service

POST https://runpay-backend-visibility-production.up.railway.app/api/call/<service_id>
Content-Type: application/json

{
  "agent_id": "agt_your_agent_id",
  "payload": { ...whatever this specific service expects... }
}

API Reference — Wallet

API Reference — Vendors

{
  "schema_input": { "type": "object", "properties": { "phone": {"type": "string"} }, "required": ["phone"] },
  "schema_output": { "type": "object", "properties": { "is_valid": {"type": "boolean"} } }
}

Enterprise — Getting Started

Organizations centralize spend, identity, and control across every agent a company runs. An organization is owned by a verified vendor account — creating one doesn't require completing Stripe payout onboarding, just a vendor account with an API key.

Members & Roles

Four roles, in order: viewer (read-only) < member (use the catalog and wallet) < admin (manage services, wallet, members) < owner (the vendor who created the organization — full control, including billing and deletion).

Shared Wallet & Spending Limits

One real shared balance, distinct from individual agent wallets. An agent explicitly linked to the organization draws exclusively from this pool for every call — never its own wallet, as long as it stays linked.

Private Marketplace

Publish internal APIs visible only to your own agents, plus an explicit allowlist of public services — never implicit access to the full public catalog.

SSO (OIDC)

SLA & Audit Log

Ownership & Deletion

Services — AI Safety

Services — Data

Services — Reasoning

Complete API Reference — Everything Else

Every remaining platform route, in one place. Descriptions marked with real response fields were derived directly from the actual code, not written from memory. Internal per-service implementation routes (the 200+ marketplace services themselves) are intentionally excluded here — browse those via GET /api/services/catalog instead.

Vendor Management (64 routes)

Agent Management (40 routes)

Admin & Platform Operations (27 routes)

Service Management (10 routes)

Agent Invoicing (4 routes)

Organizations (4 routes)

Economic Chains (3 routes)

Agent Coordination (3 routes)

Marketplace Meta (2 routes)

Sandbox (2 routes)

Support (2 routes)

(1 routes)

.well-known/agent-trust-protocol.json (1 routes)

.well-known/agent.json (1 routes)

.well-known/mcp (1 routes)

.well-known/runpay-trust-key.json (1 routes)

agent-trust-protocol.md (1 routes)

api/affiliation (1 routes)

api/analytics (1 routes)

api/call-external (1 routes)

api/config (1 routes)

api/contact-sales (1 routes)

api/discover (1 routes)

api/liability-chain (1 routes)

api/market-coverage (1 routes)

api/observability (1 routes)

api/proof-of-service (1 routes)

api/stats (1 routes)

api/test-email (1 routes)

api/transactions (1 routes)

api/verify-trust-certificate (1 routes)

health (1 routes)

internal-services/currency-exchange (1 routes)

internal-services/earthquake-search (1 routes)

internal-services/public-holidays (1 routes)

internal-services/weather-alerts-us (1 routes)

llms.txt (1 routes)

mcp (1 routes)

mcp/invoke (1 routes)

mcp/manifest (1 routes)

openapi.json (1 routes)

playground/call (1 routes)

playground/me (1 routes)

playground/quick-signup (1 routes)

playground/register-trial (1 routes)

playground/request-trial (1 routes)

playground/session (1 routes)

playground/trial (1 routes)

playground/verify (1 routes)

risk/evaluate (1 routes)

skill.md (1 routes)

webhooks/stripe (1 routes)

x402 (1 routes)

x402-flash/:serviceId (1 routes)

x402-sandbox/:serviceId (1 routes)

x402-tier/:tier_id (1 routes)

x402-with-failover/:serviceId (1 routes)

x402/:serviceId (1 routes)

xrpl/:serviceId (1 routes)

Marketplace Service Implementations (Schema Reference)

These are the real backend implementations behind catalog services — never call these /internal/* paths directly. Always invoke through POST /x402/:serviceId, using the real id from GET /api/services/catalog. Listed here for full schema transparency — descriptions were extracted directly from the real request/response fields in the code, never written from memory.