run.pay Documentation

An agent generates its own agent_id and registers it directly — no email, no human step. Useful for agent-to-agent commerce where nobody's watching.

Replace :service_id with the service UUID from the catalog.

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

Browse published, active workflows.

Real step-by-step breakdown and an estimated total price, before you run it.

Send an Idempotency-Key header (any unique string you generate per attempt) — a genuinely retried request after a dropped connection reuses the same result instead of re-running, and re-charging for, steps that already succeeded.

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

Top APIs, top AI services, and top vendors — each with Verified, Fast, Trending, Premium, and Enterprise Ready badges where genuinely earned.

{ "query": "weather forecast", "max_price_usd": 0.05 }

Returns runpay_results (payable directly, payable_via_runpay: true) and external_results — each tagged with its real source (x402_bazaar_external, circle_marketplace_external, or agent402_tools_external). Ecosystem status reported independently via coinbase_status, circle_status, agent402_status — one being down never affects the others.

Each external result includes a runpay_bridge_attempt field:

{ "available": true, "endpoint": "/api/call-external", "note": "..." }

This is an honest, experimental invitation, not a guarantee. run.pay can attempt to pay the external service with its own crypto wallet and bill you in USD via /api/call-external — verified to work end-to-end against lenient verifiers, but known to fail against some strict production verifiers for reasons not yet fully resolved. External results are never pre-certified as "payable" — that would require testing every provider with real funds, which we don't do speculatively.

Call without a PAYMENT-SIGNATURE header to receive a real 402 challenge (also mirrored in the PAYMENT-REQUIRED response header, base64-encoded):

{ "x402Version": 2, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "amount": "...", "asset": "0x8335...", "payTo": "0x...", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2" } }] }

Sign an EIP-3009 transferWithAuthorization for the exact amount, then retry the same request with PAYMENT-SIGNATURE: <base64(payload)>. The vendor is called and must succeed before any real settlement is submitted on-chain — if the vendor call fails, you are never charged.

service_id works for any active service in the catalog — find it via x402_crypto_endpoint on /api/services.

Call without a PAYMENT-CREDENTIAL header to receive a real 402 challenge (RFC 9457 Problem Details format, with a WWW-Authenticate: Payment header). Obtain a Shared Payment Granted Token (spt_...) from your own payment provider, scoped to at least the requested amount, then retry with PAYMENT-CREDENTIAL: spt_....

Services priced below $0.50 are not available via MPP — a real card network minimum, not something run.pay can waive.

Returns run.pay's real service and payment-handler manifest. Honestly scoped: run.pay sells directly-payable API calls, not shopping carts — the manifest reflects that rather than forcing generic e-commerce semantics. Declares both real payment handlers already live: x402 and mpp.

Requires the agent's real wallet_secret to prove genuine ownership before a mandate can be created for it. Body: { agent_id, signer_address, max_amount_per_call, max_total_amount, allowed_service_id, allowed_category, min_vendor_score, expires_at, signature, nonce, wallet_secret }. allowed_category and min_vendor_score are genuinely part of the cryptographically signed payload — never falsifiable metadata added after the fact. Checked automatically before every call this agent makes, until it expires, is revoked, or its total is exhausted.

Body: { agent_id, amount_usd, vendor_id, service_id }. Returns { verdict: "green"|"yellow"|"red", trust_score, reasons[] }. A non-existent agent genuinely returns red; a registered agent with no history yet returns yellow — never silently treated as fully trusted.

Body: { agent_id, description, expected_category, max_expected_amount, ttl_seconds }. Returns a short-lived intent_id (default 5 min, max 1h).

Body: { service_id, amount_usd }. Returns { matches: true|false, reason } — checks category match exactly, and amount within a real 10% tolerance of what was declared.

Body: { amount_usd, prefers_crypto }. Returns recommended_rail plus every rail's real availability — e.g. MPP is honestly marked unavailable below its real $0.50 card-network minimum. This is routing guidance only, it never executes a payment itself.

Also see GET /api/agents/:agent_id/score-explained for a real, honest breakdown of exactly how the trust score was reached — real point values, never an opaque number.

Returns totals and a real per-category breakdown. Not a legal invoice — no VAT/tax jurisdiction handling. A formatted single-transaction receipt is also available at GET /api/agents/:agent_id/accounting/receipt/:transaction_id.

Pass an optional treasury_department when creating a child via POST /api/agents/children. Returns allocated-remaining and spent totals grouped by department.

risk_alerts is honestly a live count of currently low-trust agents in the fleet — run.pay does not store a historical log of past Guard verdicts, so this is never a count of past incidents.

Body: { transaction_id }. Then view the full real chain at GET /api/observability/:transaction_id.

The service ID is the UUID from GET /api/services. Your agent's card on file is charged directly for this specific call.

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

See the Publishing a Service section above for the full signup + publish flow.

Requires your x-api-key header. Powers the vendor dashboard Overview tab — same data.

Requires your x-api-key header. Every field is optional — send only what you're changing. Real fields: active (bool), price_per_call (0.005–0.10), name, min_agent_score (0–1000 or null), high_trust_threshold / high_trust_discount_pct, trust_discount_tiers, allow_vouching.

Schema declaration: schema_input and schema_output — a real JSON Schema object for each (must include at least a type field, or the update is rejected). Most services currently have no declared schema at all — this is genuinely optional, but declaring one lets agents and integration partners validate a request before sending it, instead of guessing from examples.

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

Returns a one-time invite_token. Send it to the invitee directly — it's used at POST /api/organizations/members/accept to activate their membership and generate their own personal token.

Body: { "invite_token": "inv_..." }. Returns a personal personal_token, shown once — this authenticates the member for every role-gated action, sent as an X-Member-Token header instead of the owner's X-Api-Key.

Body: { "amount_usd": 500 }. Manual crediting for now — no self-service card charge flow exists yet specifically for wallet top-ups (distinct from the $1,999/month subscription itself, which does have real Stripe checkout).

Query param days (default 30, max 90). Returns per-agent totals and a daily trend, for agents linked to this organization's wallet.

Same validation as a public service — HTTPS required, price between $0.005–$0.10. It never appears in the public catalog, ranking, or discovery.

Body: { "task_types": ["ocr", "translation"] }. Opt-in only — an empty array (the default) means no restriction. Once set, agents linked to this organization's wallet can only call services of these types.

Sign-in URL: GET /api/organizations/:orgId/sso/login. Uses PKCE (RFC 9700) and real RS256 signature verification against your IdP's JWKS — no third-party JWT library, only Node's built-in crypto.

Measured from real health checks recorded every 5 minutes — never backfilled. If tracking began partway through the requested period, the response says so explicitly rather than treating missing history as compliant.

Membership changes, service publishing, wallet activity, config changes — each entry records whether the owner or a specific member (and their role) performed it.

The old key stops working immediately. Every agent using it needs the new one.

Body: { "new_owner_email": "..." }. The recipient must already have a vendor account. The current owner's owner-level access ends immediately.

Body: { "confirm_name": "..." } — must exactly match the organization's name. Refused if the wallet balance isn't zero. Private services are deactivated, never deleted, to preserve past transaction history.