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.

Admin role required. Only valid while the member is still pending. Issues a fresh invite_token — the previous one stops working immediately. Returns { success, email, invite_token }.

Public — no authentication. Body: { "email": "..." }. If the email belongs to an active member of this organization, a new personal token is emailed and the old one stops working. The response is always the same generic message, so the endpoint never reveals whether an email exists. Rate limited to 3 requests per hour per email.

Public — no authentication. Body: { "email": "..." }, matched against the owner agent's email on file. A wallet secret is only ever stored hashed, so it can never be recovered — it is replaced: a new one is emailed and the old one stops working at once. It controls both the owner's own agent wallet and ownership of the organization. Same generic response and same 3-per-hour limit.

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.

Viewer role. Query status (default pending), newest first, up to 100. Each item: id, agent_id, service_id, service_name, amount_usd, status, created_at, expires_at. Only agents linked to this organization appear.

Admin role. Body: { "decision": "approve" | "reject" }. Returns 403 if the approval belongs to an agent outside this organization, and 404 if it was already resolved or has expired. The decision is claimed atomically — two admins deciding at the same instant can never both succeed — and is written to the audit log.

Viewer role. Over the last 30 days: how many calls went through failover or parallel-race routing versus direct calls. Returns total_real_calls_30d, smart_routed_calls, smart_routed_pct, smart_routed_spend_usd, direct_spend_usd. Direct calls are a choice, not a failure.

Authenticated with the agent's wallet secret, or that of the organization that owns it. Returns maintain_minimum_usd, max_balance_usd and daily_call_limits — each null when unset.

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.

Admin role. Body: { "issuer_url": "https://..." } (HTTPS only). Fetches the issuer's discovery document and checks that it is reachable, that its issuer matches the URL you entered, and that token_endpoint and jwks_uri are present and safe. Returns { ok: true, issuer, token_endpoint } or { ok: false, error }. It does not verify client_id or client_secret — those can only be checked by a real sign-in.

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.

Viewer role. For every service your agents used in the last 30 days: real call count, measured_uptime_pct, and each declared SLA tier with meets_target. Computed only from your own transaction outcomes — never a vendor's self-reported figure. A service with no declared tiers has no commitment to compare against.

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.