API Documentation
Everything your AI agent needs to pay for things autonomously — within rules set by your human.
Base URL: https://youragentpays-api-production.up.railway.app
⚡ 3-Minute Quick Start
1. Human creates account at youragentpays.com
2. Human funds wallet and creates an agent → gets a yap_ API key
3. Agent uses the key to check permission and pay:
# Check if you're allowed to spend
POST /v1/check-permission
Authorization: Bearer yap_your_api_key
{ "amount_usd": "2.50", "category": "api_tools", "description": "OpenAI API call" }
# If approved: auto_approve: true — pay immediately
POST /v1/pay
{ "amount_usd": "2.50", "category": "api_tools", "description": "OpenAI API call" }
Authentication
Two types of authentication depending on who's calling:
| Caller | Header | Token format |
|---|---|---|
| Human / Dashboard | Authorization: Bearer | JWT token from /auth/login |
| AI Agent | Authorization: Bearer | yap_xxxxx (API key) |
User Auth
POST
/auth/signup
Create a new account. Returns a JWT token and auto-creates a wallet with default spending rules.
| Field | Type | Required |
|---|---|---|
| string | required | |
| password | string (min 8) | required |
POST
/auth/login
Sign in to an existing account.
Agents
GET
/agents
🔐 User JWT
List all agents for the authenticated user.
POST
/agents
🔐 User JWT
Create a new agent. Returns a
yap_ API key — only shown once.
{ "name": "My Research Agent" }
// Response
{ "id": "uuid", "name": "My Research Agent", "api_key": "yap_abc123..." }
DELETE
/agents/:id
🔐 User JWT
🛑 Kill switch. Instantly freezes the agent. Its API key stops working immediately.
POST
/agents/:id/activate
🔐 User JWT
Reactivate a frozen agent.
Wallet
GET
/wallet
🔐 User JWT
Get current balance and last 50 transactions.
POST
/wallet/fund
🔐 User JWT
Create a Stripe Checkout session to add funds. Returns a checkout URL.
{ "amount_usd": "50" }
// Response
{ "checkout_url": "https://checkout.stripe.com/..." }
Spending Rules
GET
/wallet/rules
🔐 User JWT
Get all spending rules for all categories.
PUT
/wallet/rules/:category
🔐 User JWT
Update a spending rule. Permission must be
auto, ask, or never.
{ "permission": "auto", "limit_usd": "50" }
Agent: Balance
GET
/v1/balance
🤖 Agent Key
Check your wallet balance before making a payment.
// Response
{ "balance_usd": "47.50", "balance_cents": 4750, "agent": "My Research Agent" }
Agent: Check Permission
POST
/v1/check-permission
🤖 Agent Key
Check if you're allowed to spend. Always call this before
/v1/pay for non-auto categories.
| Field | Description |
|---|---|
| amount_usd | Amount to spend (e.g. "2.50") |
| category | Spending category (see Categories) |
| description | What you're paying for (optional) |
| merchant | Who you're paying (optional) |
// Auto-approved
{ "approved": true, "auto_approve": true }
// Needs human approval
{ "approved": false, "reason": "awaiting_human_approval", "approval_id": "uuid" }
// Blocked
{ "approved": false, "reason": "category_blocked" }
// No funds
{ "approved": false, "reason": "insufficient_balance" }
Agent: Pay
POST
/v1/pay
🤖 Agent Key
Execute a payment. For
auto categories, call directly. For ask categories, include the approval_id from /v1/check-permission.
// Auto category — pay directly
POST /v1/pay
{ "amount_usd": "2.50", "category": "api_tools", "description": "GPT-4 API call", "merchant": "OpenAI" }
// After human approval
POST /v1/pay
{ "amount_usd": "25.00", "category": "cloud_hosting", "approval_id": "uuid-from-check-permission" }
// Response
{ "success": true, "tx_id": "yap_tx_abc123", "amount_usd": "2.50", "remaining_usd": "45.00" }
Agent: Request Funds
POST
/v1/request-funds
🤖 Agent Key
Notify your human that you're running low and need a top-up.
{ "amount_usd": "50", "reason": "Running low — need funds for upcoming research tasks" }
Spending Categories
| Category | Description | Default |
|---|---|---|
| api_tools | External API calls (any service) | auto |
| ai_credits | AI model providers (OpenAI, Anthropic, etc.) | auto |
| research | Data feeds, search APIs, news | auto |
| storage | Files, databases, CDN | auto |
| cloud_hosting | Servers, compute, infrastructure | ask |
| domains | Domain registration and DNS | ask |
| other | Everything else | ask |
Error Codes
| HTTP | Code | Meaning |
|---|---|---|
| 401 | — | Invalid or revoked API key / JWT |
| 402 | insufficient_balance | Not enough funds in wallet |
| 403 | payment_requires_approval | Call /v1/check-permission first |
| 403 | category_blocked | Human set this category to "never" |
| 404 | — | Resource not found |
| 409 | — | Email already registered |
Ready to give your agent purchasing power?
Sign up free. No credit card required to start.
Get Started →