run.pay Documentation

run.pay is a Stripe-native marketplace where AI agents autonomously discover and purchase API services. Sellers publish any function and get paid per call via Stripe Connect.

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

Who	What you do	Time
Seller	Register → Publish a service → Get paid per call	10 min
Agent dev	Register agent → Add MCP config → Agents pay automatically	5 min

Quickstart — Sell your first API

Step 1 — Create your vendor account

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

You'll receive an api_key (vnd_...) and a stripe_onboarding_url. Open the Stripe URL to connect your bank account.

Step 2 — Publish a service

curl -X POST https://runpay-backend-visibility-production.up.railway.app/api/services \
  -H "X-Api-Key: vnd_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web Scraper",
    "description": "Extract content from any URL",
    "endpoint_url": "https://your-server.com/scrape",
    "price_per_call": 0.005,
    "category": "DATA"
  }'

Step 3 — That's it

Your service is now live in the marketplace. AI agents can discover it via MCP and pay automatically via Stripe.

MCP Configuration

Add run.pay to your agent's MCP config to give it access to all marketplace services.

Claude Desktop / claude_desktop_config.json

{
  "mcpServers": {
    "runpay": {
      "url": "https://runpay-backend-visibility-production.up.railway.app/mcp"
    }
  }
}

Cursor / .cursor/mcp.json

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

Available MCP tools

Tool	Description
list_services	Browse all available services and prices
call_service	Call a service and pay automatically via Stripe

Register as a Seller

POST /api/vendors/register

Creates a vendor account and a Stripe Connect account for payouts.

Field	Type	Description
email	`string`	Your email address
name	`string`	Your name or company
plan	`starter \| growth`	starter = free 2%, growth = $49/mo 1%

Response: vendor_id, api_key, stripe_onboarding_url

Publish a Service

POST /api/services

Publish a service to the marketplace. Requires X-Api-Key header.

Field	Type	Description
name	`string`	Service name
description	`string`	What it does
endpoint_url	`string`	Your API endpoint (POST)
price_per_call	`number`	Price in USD (min $0.001)
category	`string`	DATA, AI, SEARCH, MEDIA...

Your endpoint must accept POST JSON and return JSON. run.pay calls it after payment is confirmed.

Your endpoint requirements

// Your endpoint receives:
POST https://your-server.com/your-service
Headers:
  X-RunPay-Call-Id: uuid
  X-RunPay-Agent: agent_id
Body: { ...payload from agent }

// Your endpoint must return:
{ "result": "..." }  // any JSON

Analytics

GET /api/vendors/analytics?period=30d

Returns stats for your services. Requires X-Api-Key header.

period: 7d, 30d, 90d

Register an Agent

POST /api/agents/register

Creates a Stripe wallet for your agent. Returns a client_secret to attach a payment method.

Field	Type	Description
agent_id	`string`	Unique identifier for your agent

curl -X POST https://runpay-backend-visibility-production.up.railway.app/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "my-agent-001" }'

Call a Service

POST /api/call/:service_id

Calls a service and charges the agent via Stripe automatically.

Field	Type	Description
agent_id	`string`	Your agent's unique ID
payload	`object`	Data to send to the service

curl -X POST https://runpay-backend-visibility-production.up.railway.app/api/call/SERVICE_ID \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent-001",
    "payload": { "url": "https://example.com" }
  }'

Marketplace API

GET /api/marketplace

Returns all active services. Public endpoint, no auth required.

Query params: category, search, limit, offset

GET /api/marketplace/:id

Returns details for a specific service.

Error Codes

Code	Meaning	Fix
401	Invalid API key	Check your X-Api-Key header
402	Payment failed	Agent wallet not configured or card declined
404	Service not found	Check service_id or service is inactive
502	Service unavailable	Seller endpoint returned error — refund issued automatically

Automatic refunds: if your endpoint fails, run.pay automatically refunds the agent. No manual intervention needed.