API Reference

Complete reference for all x402 Payment Gateway endpoints.

Base URL: https://x402.serendb.com

Authentication

Provider endpoints require API key authentication via the X-API-Key header:

X-API-Key: seren_live_your_api_key_here

Agent endpoints require the agent's wallet address in the request body.

Provider Endpoints

Register Provider

Endpoint: POST /api/providers/register

Request Body:

{
  "name": "string",           // Provider name (required)
  "email": "string",          // Contact email (required)
  "walletAddress": "string",  // Ethereum address for receiving USDC (required, must start with 0x)
  "connectionString": "string" // PostgreSQL connection string (required)
}

Response: 201 Created

{
  "provider": {
    "id": "uuid",
    "name": "string",
    "email": "string",
    "walletAddress": "string",
    "provisionedByGateway": false,
    "createdAt": "timestamp"
  },
  "apiKey": "string"          // Save this securely!
}

Errors:

400 Bad Request - Invalid input data
409 Conflict - Email or wallet address already registered
500 Internal Server Error - Server error

Example:

curl -X POST https://x402.serendb.com/api/providers/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Yearn Finance DB",
    "email": "provider@yearn.finance",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "connectionString": "postgresql://user:pass@host:5432/db"
  }'

Configure Pricing

Set or update pricing configuration for your database.

Endpoint: POST /api/providers/:id/pricing

Authentication: Required (X-API-Key header)

Path Parameters:

id (uuid) - Provider ID from registration

Request Body:

{
  "basePricePer1000Rows": 1.0,  // Base price in USDC per 1000 rows
  "markupMultiplier": 2.0        // Markup multiplier (1.0 = no markup, 2.0 = 2x)
}

Response: 200 OK

{
  "id": "uuid",
  "providerId": "uuid",
  "basePricePer1000Rows": 1.0,
  "markupMultiplier": 2.0,
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

Errors:

401 Unauthorized - Missing or invalid API key
404 Not Found - Provider not found
400 Bad Request - Invalid pricing values
500 Internal Server Error - Server error

Example:

curl -X POST https://x402.serendb.com/api/providers/945349e6-6d49-4c07-9257-2f2839e07173/pricing \
  -H "Content-Type: application/json" \
  -H "X-API-Key: seren_live_b79b94cdae0860ec2e7fd4cc922eb409" \
  -d '{
    "basePricePer1000Rows": 1.0,
    "markupMultiplier": 2.0
  }'

Agent Endpoints

Check Balance

Check an AI agent's USDC balance for a specific provider.

Endpoint: GET /api/balance/:wallet/:providerId

Path Parameters:

wallet (string) - Agent's Ethereum wallet address (must start with 0x)
providerId (uuid) - Provider ID

Response: 200 OK

{
  "agentWallet": "string",
  "providerId": "uuid",
  "balance": "string",        // USDC balance as string (6 decimals)
  "updatedAt": "timestamp|null"
}

Errors:

400 Bad Request - Invalid wallet address or provider ID
500 Internal Server Error - Server error

Example:

curl https://x402.serendb.com/api/balance/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1/945349e6-6d49-4c07-9257-2f2839e07173

Deposit USDC

Verify and credit a USDC deposit from Base network.

Endpoint: POST /api/deposit

Request Body:

{
  "txHash": "string",         // Base network transaction hash (must start with 0x)
  "agentWallet": "string",    // Agent's Ethereum wallet address
  "providerId": "uuid"        // Provider ID
}

Response: 200 OK

{
  "success": true,
  "balance": "string",        // New balance after deposit
  "transaction": {
    "txHash": "string",
    "amount": "string",       // Deposited amount
    "verified": true
  }
}

Errors:

400 Bad Request - Invalid transaction hash, wallet, or provider ID
409 Conflict - Transaction already processed
402 Payment Required - Transaction not found or insufficient amount
500 Internal Server Error - Blockchain verification failed

Example:

curl -X POST https://x402.serendb.com/api/deposit \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "agentWallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "providerId": "945349e6-6d49-4c07-9257-2f2839e07173"
  }'

Execute Query

Execute a SQL query after verifying sufficient balance.

Endpoint: POST /api/query

Request Body:

{
  "sql": "string",            // SQL query to execute
  "agentWallet": "string",    // Agent's Ethereum wallet address
  "providerId": "uuid"        // Provider ID
}

Response: 200 OK

{
  "rows": [],                 // Query results
  "rowCount": 0,              // Number of rows returned
  "estimatedCost": "string",  // Estimated cost before execution
  "actualCost": "string",     // Actual cost charged
  "executionTime": "string"   // Query execution time (e.g., "45ms")
}

Errors:

400 Bad Request - Invalid SQL, wallet, or provider ID
402 Payment Required - Insufficient balance
403 Forbidden - SQL query not allowed (e.g., DROP, DELETE without WHERE)
404 Not Found - Provider or pricing not found
500 Internal Server Error - Query execution failed

Example:

curl -X POST https://x402.serendb.com/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM users LIMIT 10",
    "agentWallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "providerId": "945349e6-6d49-4c07-9257-2f2839e07173"
  }'

Security Notes:

Dangerous SQL operations (DROP, TRUNCATE, etc.) are blocked
DELETE/UPDATE without WHERE clause are blocked
SQL injection protection is enabled
Query timeouts enforced (10 seconds max)

Transaction History

Retrieve transaction history for an agent.

Endpoint: GET /api/transactions/:wallet

Path Parameters:

wallet (string) - Agent's Ethereum wallet address

Query Parameters:

providerId (uuid) - Filter by provider (optional)
limit (number) - Maximum transactions to return (default: 50, max: 100)

Response: 200 OK

{
  "agentWallet": "string",
  "transactions": [
    {
      "id": "string",
      "type": "deposit|query",
      "amount": "string",       // Positive for deposits, negative for queries
      "balanceBefore": "string",
      "balanceAfter": "string",
      "txHash": "string|null",  // Only for deposits
      "metadata": {},           // Query details for query transactions
      "timestamp": "timestamp"
    }
  ]
}

Errors:

400 Bad Request - Invalid wallet address
500 Internal Server Error - Server error

Example:

curl "https://x402.serendb.com/api/transactions/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1?providerId=945349e6-6d49-4c07-9257-2f2839e07173&limit=50"

System Endpoints

Health Check

Check if the gateway is operational.

Endpoint: GET /api/health

Response: 200 OK

{
  "status": "healthy",
  "timestamp": "timestamp"
}

Example:

curl https://x402.serendb.com/api/health

Rate Limiting

All endpoints are rate-limited to prevent abuse:

General endpoints: 100 requests per 15 minutes per IP
Query endpoint: 20 requests per 15 minutes per IP
Deposit endpoint: 10 requests per 15 minutes per IP

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699876543

When rate limit is exceeded:

{
  "error": "Too many requests",
  "retryAfter": 900
}

Error Responses

All errors follow this format:

{
  "error": "Human-readable error message"
}

HTTP Status Codes:

200 OK - Success
201 Created - Resource created
400 Bad Request - Invalid input
401 Unauthorized - Missing/invalid authentication
402 Payment Required - Insufficient balance
403 Forbidden - Operation not allowed
404 Not Found - Resource not found
409 Conflict - Resource already exists
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

CORS Support

The API supports CORS for browser-based applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-API-Key

Base Network Details

Network: Base (Ethereum L2) USDC Contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 Chain ID: 8453 Block Explorer: https://basescan.org

SDK and Libraries

Coming soon:

JavaScript/TypeScript SDK
Python SDK
Rust SDK

For now, use standard HTTP clients (fetch, axios, requests, etc.).

Need Help?

Get Started Guide
Pricing Models
Examples
GitHub Issues: https://github.com/serenorg/serenai-x402/issues

PreviousGet Started NextExamples

Last updated 17 days ago