Documentation

API Reference

Everything you need to integrate agentsvc.io into your agent. Payments run on the x402 protocol with USDC on Base.

Quickstart

Start by listing available services. No API key or authentication required.

bash
# 1. List all available services
curl https://agentsvc.io/api/v1/services

# 2. Filter by category and max price
curl "https://agentsvc.io/api/v1/services?category=visual&max_price=0.01"

# 3. Get a specific service
curl https://agentsvc.io/api/v1/services/screenshot

To call a service, send a POST request with the x402 payment header:

bash
# Call the Screenshot API with x402 payment
curl -X POST https://agentsvc.io/api/v1/services/screenshot/call \
  -H "Content-Type: application/json" \
  -H "X-Payment: x402 usdc base <your-signed-payment>" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "full_page": false
  }'
json
{
  "success": true,
  "data": {
    "image_base64": "iVBORw0KGgoAAAANS...",
    "width": 1280,
    "height": 800,
    "url": "https://example.com",
    "captured_at": "2025-04-06T12:00:00.000Z"
  }
}

x402 Payment Flow

agentsvc.io uses the x402 protocol — a standard for micropayments over HTTP using USDC on the Base blockchain. No subscription required, pay only for what you use.

1

Call the endpoint

Send a POST request to the service endpoint without a payment header.

POST /api/v1/services/screenshot/call
Content-Type: application/json

{ "url": "https://example.com" }
2

Receive HTTP 402

The server responds with 402 Payment Required and details about the payment needed.

HTTP/1.1 402 Payment Required
X-Payment-Required: usdc base 0.005
Content-Type: application/json

{
  "error": "payment_required",
  "amount_usdc": "0.005",
  "chain": "base",
  "receiving_address": "0x..."
}
3

Sign and attach payment

Sign the USDC payment on Base and attach it as an X-Payment header.

POST /api/v1/services/screenshot/call
Content-Type: application/json
X-Payment: x402 usdc base eyJ...<signed-payload>

{ "url": "https://example.com" }
4

Receive the response

The payment is verified on-chain. The service executes and returns the result.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "data": { ... }
}

Service Schema

Every service in the catalog follows this TypeScript interface:

typescript
type ServiceCategory = 'visual' | 'data' | 'text' | 'utility' | 'finance';

interface Service {
  id: string;                 // Unique service identifier
  slug: string;               // URL-friendly identifier
  name: string;               // Human-readable name
  description: string;        // What the service does
  category: ServiceCategory;  // Service category
  endpoint: string;           // Full POST endpoint URL
  price_usdc: number;         // Cost in USDC per call (e.g. 0.005)
  latency_p99_ms: number;     // 99th percentile latency in ms
  input_schema: object;       // JSON Schema for request body
  output_schema: object;      // JSON Schema for response data
  is_active: boolean;         // Whether the service is available
  provider: string;           // Service provider identifier
  tags: string[];             // Searchable tags
}

The catalog API returns a paginated list response:

typescript
interface CatalogResponse {
  success: boolean;
  data: Service[];
  meta: {
    total: number;     // Total matching services
    limit: number;     // Items per page (default: 20)
    offset: number;    // Pagination offset
  };
  error?: string;      // Only present on failure
}

Supported query parameters for GET /api/v1/services:

qstringFull-text search across name, description, and tags
categorystringFilter by category: visual, data, text, utility, finance
max_pricenumberMaximum price in USDC (e.g. 0.01)
limitintegerResults per page, max 100, default 20
offsetintegerPagination offset, default 0

Error Codes

All error responses follow the same structure:

json
{
  "success": false,
  "error": "payment_required",
  "message": "Include X-Payment header with USDC payment on Base"
}
CodeStatusDescription
400Bad RequestMissing or invalid parameters in the request body.
402Payment RequiredNo X-Payment header provided, or payment is invalid/insufficient.
404Not FoundThe requested service slug does not exist.
429Too Many RequestsRate limit exceeded. See X-RateLimit-* headers for details.
500Internal Server ErrorUpstream service error. Retry with exponential backoff.

Rate Limits

Rate limits apply per IP address. Limits are communicated via response headers.

Catalog API (/api/v1/services)100 requests / minute
Service calls (/api/v1/proxy/*)60 requests / minute
Burst allowance20 requests / 10 seconds
bash
# Rate limit headers in every response:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1712403600

# When rate limited (429):
Retry-After: 42

Submit a Service

Want to offer your service to AI agents? Submit it to the marketplace and start earning USDC micropayments automatically.

Requirements for listed services:

  • Expose a JSON-based POST endpoint
  • Return structured, deterministic output
  • Support the x402 payment header for USDC on Base
  • Provide a JSON Schema for input and output
  • Maintain 99.5% uptime SLA
  • P99 latency under 10 seconds
Submit via Email →