# Semagram Agent API

Machine-to-machine search API for Telegram channels, groups, and bots. Payments are handled via the [x402 protocol](https://www.x402.org/) — no API keys or subscriptions required.

## Endpoint

```
GET /api/agent/search?q=<query>&limit=<n>&lang=<code>&kind=<type>&min_users=<n>&max_users=<n>
```

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `q`       | Yes      | —       | Search query (semantic) |
| `limit`   | No       | 100     | Max number of results (1-1000) |
| `lang`    | No       | —       | Language filter (ISO 639-1 code, e.g. "en", "ru") |
| `kind`    | No       | —       | Entity type filter ("channel", "group", or "bot") |
| `min_users` | No     | —       | Minimum subscriber/member count |
| `max_users` | No     | —       | Maximum subscriber/member count |

## Authentication

This endpoint uses the **x402 payment protocol** (HTTP 402 Payment Required).

1. Send a request without payment headers.
2. The server responds with `402 Payment Required` and a `PAYMENT-REQUIRED` header containing payment requirements (recipient address, token, amount, network).
3. Create a payment authorization matching the requirements and resend the request with a `PAYMENT` header.
4. On a successful response (2xx), the payment is settled on-chain. On errors (4xx/5xx), no payment is charged.

Use an x402-compatible HTTP client (e.g., [x402-fetch](https://www.npmjs.com/package/x402-fetch), [x402-reqwest](https://crates.io/crates/x402-reqwest)) to handle the payment flow automatically.

## Pricing

Price scales with the requested `limit` parameter:

| Limit     | Price (USDC) |
|-----------|-------------|
| 1-100     | 0.01        |
| 101-200   | 0.02        |
| 201-300   | 0.03        |
| 301-400   | 0.04        |
| 401-500   | 0.05        |
| 501-600   | 0.06        |
| 601-700   | 0.07        |
| 701-800   | 0.08        |
| 801-900   | 0.09        |
| 901-1000  | 0.10        |

Formula: `ceil(limit / 100) * 0.01 USDC`

## Response

**Content-Type:** `application/json`

```json
[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "kind": "channel",
    "username": "example_channel",
    "name": "Example Channel",
    "bio": null,
    "description": "An example Telegram channel",
    "avatar_url": "https://example.com/avatar.jpg",
    "user_count": 15000
  }
]
```

| Field        | Type     | Description |
|-------------|----------|-------------|
| `uuid`      | string   | Unique identifier |
| `kind`      | string?  | `"channel"`, `"group"`, `"bot"`, or `null` |
| `username`  | string   | Telegram username |
| `name`      | string?  | Display name |
| `bio`       | string?  | Short bio |
| `description` | string? | Full description |
| `avatar_url` | string? | Avatar image URL |
| `user_count` | number? | Subscriber/member count |

## Errors

| Status | Meaning |
|--------|---------|
| 400    | Empty or missing `q` parameter |
| 402    | Payment required (see Authentication) |
| 502    | Upstream search service unavailable |

## Example

Using `curl` (manual flow):

```bash
# 1. Initial request returns 402 with payment requirements
curl -i 'https://semagram.io/api/agent/search?q=crypto+news'

# 2. Use an x402 client library to handle payment automatically
```

Using `x402-fetch` (JavaScript):

```javascript
import { wrapFetch } from "x402-fetch";

const fetch402 = wrapFetch(fetch, wallet);
const res = await fetch402("https://semagram.io/api/agent/search?q=crypto+news");
const results = await res.json();
```

## Links

- [x402 Protocol](https://www.x402.org/)
- [x402 Documentation](https://docs.cdp.coinbase.com/x402/welcome)