Semagram Agent API

Endpoint

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

Authentication

This endpoint uses the x402 payment protocol (HTTP 402 Payment Required). No API keys or subscriptions needed.

1. Send a request without payment headers.
2. The server responds with 402 and payment requirements (recipient, token, amount, network).
3. Create a payment authorization and resend with a PAYMENT header.
4. On success (2xx), payment is settled on-chain. On errors (4xx/5xx), no payment is charged.

Use an x402-compatible client to handle the payment flow automatically: x402-fetch, x402-reqwest.

Response

[
  {
    "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
  }
]

Errors

Example

Using x402-fetch (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
• x402 Documentation
• Raw API docs (Markdown)