Get Started

Set up your database provider account and start accepting payments from AI agents in minutes.

Prerequisites

Before you begin, ensure you have:

• A SerenDB database instance (or compatible PostgreSQL database)

• An Ethereum wallet address for receiving USDC payments

• Your database connection string

Step 1: Register as a Provider

Register your database with the x402 Gateway:

curl -X POST https://x402.serendb.com/api/providers/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Database",
    "email": "[e-mail]",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "connectionString": "postgresql://user:password@host:5432/database"
  }'

Response:

{
  "provider": {
    "id": "945349e6-6d49-4c07-9257-2f2839e07173",
    "name": "My Database",
    "email": "[e-mail]",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
    "createdAt": "2025-11-13T07:55:35.112Z"
  },
  "apiKey": "seren_live_b79b94cdae0860ec2e7fd4cc922eb409"
}

Important: Save your apiKey securely - you'll need it for all provider operations.

Step 2: Configure Pricing

Set your pricing model using your provider ID and API key:

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
  }'

Response:

{
  "id": "243405fe-bc2a-41da-9898-8358023bb50f",
  "providerId": "945349e6-6d49-4c07-9257-2f2839e07173",
  "basePricePer1000Rows": 1.0,
  "markupMultiplier": 2.0,
  "createdAt": "2025-11-13T07:55:50.474Z"
}

This configuration charges:

• $1.00 USDC per 1000 rows returned

• 2.0x markup on the base price

• Final cost: $2.00 USDC per 1000 rows

See Pricing Models for advanced pricing strategies.

Step 3: Test with an AI Agent

Check Agent Balance

Before executing queries, AI agents should check their balance:

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

Response (no balance):

{
  "agentWallet": "0xAgentWalletAddress",
  "providerId": "945349e6-6d49-4c07-9257-2f2839e07173",
  "balance": "0",
  "updatedAt": null
}

Deposit USDC

If balance is insufficient, the agent deposits USDC on Base network:

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

Response:

{
  "success": true,
  "balance": "100.000000",
  "transaction": {
    "txHash": "0x1234567890abcdef...",
    "amount": "100.000000",
    "verified": true
  }
}

Execute Query

With sufficient balance, execute SQL queries:

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

Response:

{
  "rows": [
    {"id": 1, "name": "Alice", "email": "[e-mail]"},
    {"id": 2, "name": "Bob", "email": "[e-mail]"}
  ],
  "rowCount": 10,
  "estimatedCost": "0.020000",
  "actualCost": "0.020000",
  "executionTime": "45ms"
}

Cost calculation: 10 rows × ($1.00 / 1000) × 2.0 markup = $0.02 USDC

Step 4: Monitor Usage

View Transaction History

Track all agent transactions:

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

Response:

{
  "agentWallet": "0xAgentWalletAddress",
  "transactions": [
    {
      "id": "tx_123",
      "type": "deposit",
      "amount": "100.000000",
      "balanceBefore": "0.000000",
      "balanceAfter": "100.000000",
      "txHash": "0x1234567890abcdef...",
      "timestamp": "2025-11-13T08:00:00.000Z"
    },
    {
      "id": "tx_124",
      "type": "query",
      "amount": "-0.020000",
      "balanceBefore": "100.000000",
      "balanceAfter": "99.980000",
      "metadata": {
        "sql": "SELECT * FROM users LIMIT 10",
        "rowCount": 10
      },
      "timestamp": "2025-11-13T08:01:00.000Z"
    }
  ]
}

Check Health Status

Verify the gateway is operational:

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

Response:

{
  "status": "healthy",
  "timestamp": "2025-11-13T08:00:00.000Z"
}

Security Best Practices

Protect Your API Key

• Never commit API keys to version control

• Store in environment variables or secret management systems

• Rotate keys periodically

Connection String Security

• Use read-only database credentials when possible

• Enable SSL/TLS for database connections

• Implement IP whitelisting if available

Monitor Suspicious Activity

• Set up alerts for unusual transaction patterns

• Review transaction history regularly

• Monitor agent wallet addresses for abuse

Next Steps

• API Reference - Complete endpoint documentation

• Pricing Models - Advanced pricing strategies

• Examples - Integration examples for AI agents

Need Help?

• GitHub Issues: https://github.com/serenorg/serenai-x402/issues

• Email: [e-mail]

• Discord: [Coming Soon]