API Documentation

Complete reference for the Obolos API Marketplace powered by x402 protocol.

Getting Started

Obolos is an API marketplace with pay-per-request pricing via the x402 protocol. No subscriptions, no quotas - pay only for what you use.

Quick Start

  1. Browse available APIs on the Marketplace
  2. Choose a wallet address (any unique string) and top up credits
  3. Call APIs via /api/:slug (e.g., /api/pdf-parser) with your wallet as a bearer token
# 1. Top up credits
curl -X POST https://obolos.tech/api/wallet/topup \
  -H "Content-Type: application/json" \
  -d '{"address": "my-wallet", "amount": 100}'

# 2. Check balance
curl -H "Authorization: Bearer my-wallet" \
  https://obolos.tech/api/wallet/balance

# 3. Call a marketplace API (e.g., OCR Text Extraction)
curl -X POST https://obolos.tech/api/ocr-text-extraction \
  -H "Authorization: Bearer my-wallet" \
  -F "file=@document.png"

Authentication

There are two ways to authenticate API requests:

1. Bearer Token (Credit-based)

Use your wallet address as a bearer token. Credits are deducted per call.

Authorization: Bearer <wallet-address>

2. x402 Payment (USDC)

Pay directly with USDC on Base via the x402 protocol. Include a payment header with your request:

X-Payment: <base64-encoded-payment-payload>

See the x402 Protocol section for details.

Pricing

Each marketplace API has its own price set by the seller. Prices are in USDC. 1 credit = $0.001 USD

Loading pricing data...

Prices are set by API sellers and may change. Browse the Marketplace for the latest pricing.

Wallet Endpoints

Manage your credit balance. These endpoints are free.

GET /api/wallet/balance

Get your current credit balance.

Headers: Authorization: Bearer <address>

{
  "address": "my-wallet",
  "credits": 95,
  "creditValue": "$0.095 USD"
}
GET /api/wallet/transactions

Get transaction history.

Headers: Authorization: Bearer <address>

{
  "transactions": [
    {
      "id": "tx_abc123",
      "amount": 100,
      "description": "Manual top-up",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "tx_def456",
      "amount": -10,
      "description": "Proxy call: OCR Text Extraction",
      "created_at": "2024-01-15T10:35:00Z"
    }
  ]
}
POST /api/wallet/topup

Add credits to a wallet. (Dev/test mode - no payment required)

Body:

{
  "address": "my-wallet",
  "amount": 100
}

Response:

{
  "success": true,
  "transaction": { "id": "tx_...", "amount": 100, ... },
  "newBalance": 100
}

Marketplace API Endpoints

All marketplace APIs are called through clean slug-based routes like /api/pdf-parser. Payment is required via x402 or bearer token credits.

* /api/:slug varies

Call a marketplace API by its slug name. Also accessible via /api/proxy/:apiId with UUID. The request body and response depend on the specific API.

Headers: Authorization: Bearer <address> or X-Payment: <x402-payload>

Example:

curl -X POST https://obolos.tech/api/ocr-text-extraction \
  -H "Authorization: Bearer my-wallet" \
  -F "file=@document.png"

curl -X POST https://obolos.tech/api/pdf-parser \
  -H "Authorization: Bearer my-wallet" \
  -F "file=@document.pdf"
GET /api/marketplace/apis

Browse all available APIs on the marketplace. No authentication required. Returns slug for each API.

GET /api/marketplace/apis

{
  "apis": [
    {
      "id": "60b0772e-...",
      "name": "PDF Parser",
      "slug": "pdf-parser",
      "price_per_call": 0.02,
      "http_method": "POST",
      ...
    }
  ]
}

Available APIs

Loading available APIs...

Error Handling

The API uses standard HTTP status codes:

Error Response Format

{
  "error": "Error type",
  "message": "Human-readable description"
}

x402 Protocol

When you call a marketplace API without payment, you receive an HTTP 402 response with x402 payment requirements:

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: <base64-encoded-requirements>

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "20000",
    "payTo": "0x...",
    "maxTimeoutSeconds": 60,
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  }],
  "resource": {
    "url": "https://obolos.tech/api/proxy/60b0772e-...",
    "description": "PDF Parser API call",
    "mimeType": "application/json"
  },
  "error": "Payment of $0.0200 USDC required for PDF Parser"
}

To resolve:

  1. With credits: Call POST /api/wallet/topup to add credits, then retry with Authorization: Bearer <address>
  2. With x402: Submit USDC payment on Base and include the X-Payment header

Benefits of x402