# SerenAI

> Pay-per-query data marketplace for AI agents. Discover 75+ data publishers and query them with micropayments.

SerenAI connects AI agents to data publishers. Query databases, APIs, and services from verified publishers using prepaid credits or on-chain payments. No subscriptions—pay only for what you use.

## Quick Start for AI Agents

**To query a data publisher:**

1. **Discover** - Find relevant data sources
   `GET /agent/publishers/suggest?query=weather data for San Francisco`

2. **Estimate cost** - Check price before executing
   `POST /agent/estimate` with your query

3. **Execute** - Run the paid query
   `POST /agent/database` for SQL queries
   `POST /agent/api` for HTTP API calls

4. **Check balance** - Monitor your credits
   `GET /agent/wallet/balance`

## Authentication

```
Authorization: Bearer seren_live_xxxxx
```

Base URL: `https://api.serendb.com`

---

## Agent Marketplace (Primary API)

Use these endpoints to discover and query data publishers.

### Discover Publishers

| Endpoint | Use When |
|----------|----------|
| `GET /agent/publishers` | Browse all active publishers |
| `GET /agent/publishers/suggest?query=<task>` | AI-powered suggestions for your task |
| `GET /agent/publishers/{slug}` | Get details about a specific publisher |

**Example - Find publishers for a task:**
```
GET /agent/publishers/suggest?query=scrape website content&limit=5
```

**Example - Search publishers:**
```
GET /agent/publishers?search=financial&is_verified=true&limit=20
```

### Query Publishers

| Endpoint | Use When |
|----------|----------|
| `POST /agent/database` | Query a publisher's database (SQL) |
| `POST /agent/api` | Call a publisher's HTTP API |
| `POST /agent/stream` | Stream large responses |
| `POST /agent/estimate` | Check cost before executing |

**Example - Database query:**
```json
POST /agent/database
{
  "publisher_slug": "financial-news",
  "query": "SELECT headline, summary FROM articles WHERE topic = 'AI' ORDER BY published_at DESC LIMIT 10"
}
```

**Example - API call:**
```json
POST /agent/api
{
  "publisher_slug": "web-scraper",
  "method": "POST",
  "path": "/extract",
  "body": { "url": "https://example.com", "selectors": ["h1", "p"] }
}
```

**Example - Estimate cost first:**
```json
POST /agent/estimate
{
  "publisher_slug": "financial-news",
  "query": "SELECT * FROM articles LIMIT 100"
}
// Response: { "estimated_cost": { "amount": "0.05", "asset": "USDC" } }
```

### Wallet & Payments

| Endpoint | Use When |
|----------|----------|
| `GET /agent/wallet/balance` | Check prepaid balance |
| `POST /agent/wallet/deposit` | Add funds via Stripe |
| `POST /agent/deposit` | Add funds via on-chain payment |
| `GET /agent/wallet/transactions` | View transaction history |

**Payment Methods:**
- **Prepaid balance**: Include `Authorization: Bearer <token>` header
- **On-chain (x402)**: If no auth header, returns 402 with payment instructions

### Publisher Response Format

Successful queries return:
```json
{
  "data": { ... },
  "cost": { "amount": "0.01", "asset": "USDC" },
  "publisher": { "slug": "...", "name": "..." }
}
```

---

## Projects & SQL Execution

For users hosting their own databases on SerenAI.

### Projects

| Endpoint | Description |
|----------|-------------|
| `POST /projects` | Create a new project |
| `GET /projects` | List your projects |
| `GET /projects/{project_id}` | Get project details |
| `DELETE /projects/{project_id}` | Delete a project |

**Example - Create project:**
```json
POST /projects
{
  "name": "my-analytics-db",
  "region": "us-east-1"
}
```

### SQL Execution

| Endpoint | Description |
|----------|-------------|
| `POST /projects/{project_id}/branches/{branch_id}/sql` | Execute SQL query |
| `POST /projects/{project_id}/branches/{branch_id}/sql/transaction` | Execute transaction |
| `GET /projects/{project_id}/branches/{branch_id}/connection-string` | Get connection string |

**Example - Execute SQL:**
```json
POST /projects/{project_id}/branches/{branch_id}/sql
{
  "query": "SELECT * FROM users WHERE active = true",
  "params": []
}
```

---

## Common Errors

| Code | Meaning | Solution |
|------|---------|----------|
| 402 | Payment Required | Add funds or include payment header |
| 404 | Publisher not found | Verify slug with `GET /agent/publishers` |
| 429 | Rate limited | Wait and retry (100 req/min standard) |
| 401 | Unauthorized | Check API key format: `Bearer seren_live_xxx` |

---

## Integration Options

**MCP Server** (recommended for Claude, Cursor, Windsurf):
```bash
# Universal installer (auto-detects all MCP clients)
curl -fsSL https://serendb.com/install.sh | bash

# Or manually for Claude Code:
claude mcp add --transport http -s user seren https://mcp.serendb.com/mcp
```
See [MCP Installation Guide](/guides/mcp-install.html) for all platforms.

**REST API** (for custom agents):
Use the endpoints documented above with any HTTP client.

---

## Optional

- [Full API Reference](/llms-full.txt) - Complete endpoint documentation
- [Create Publisher Guide](/guides/create-publisher.html) - Complete schema and curl examples
- [MCP Publishers Guide](/guides/mcp-publishers.html) - MCP server integration
- [MCP Tool Schemas](/install-seren/tools.json) - Machine-readable tool definitions
- [OpenAPI Specification](https://api.serendb.com/openapi.json) - Full OpenAPI spec