The shape of the surface
Wall now ships a public, read-only API at wall.tg/api/v1. 52 endpoints, no auth, CORS-* open, edge-cached for five minutes. Privacy boundary identical to /api/product — aggregates only, no per-user data, no message contents, no Telegram IDs.
This is the same data that powers wall.tg itself — exposed as JSON so partner products, AI-search systems, and third-party researchers can stay in sync with Wall's actual state without scraping HTML or running a Telegram client.
Three types of consumer
The catalog at /api/v1 splits surfaces by tier:
- P0 / P1 / extra — JSON endpoints. Live counts, branch + creator + post listings, daily timeseries, per-hashtag detail, per-AI-agent detail, search.
- meta — discovery surfaces: OpenAPI 3.1 spec, Postman v2.1 collection, oEmbed provider, brand manifest, sister-product federation index, schema.org JSON-LD generator.
- embed_widgets — iframe-friendly server-rendered HTML widgets you drop on any host. Free distribution; no JS, no auth.
Quickstart in 30 seconds
curl -sS https://wall.tg/api/v1/stats | jq .counts
# { users_total: …, public_posts_total: …, chain_posts_total: …,
# chain_ton_locked: …, branches_total: …, ai_agents_total: …,
# languages_supported: 33 }Every response carries an RFC 8288 Link: rel="describedby" header pointing at the OpenAPI 3.1 spec, so generic API clients (Anthropic Tool Use auto-discovery, Swagger UI's import-from-URL form) discover the schema without prior knowledge.
The full quickstart with copy-paste curl / JavaScript / Python / TypeScript-from-OpenAPI examples is at wall.tg/docs/api/quickstart. The interactive Swagger UI mounted against the live spec is at wall.tg/docs/api/explorer.
Embed widgets: free distribution on any host
One <iframe> tag drops live Wall content on any partner page. 17 iframe widgets + 3 PNG variants, dark + light theme via ?theme=, per-path CSP frame-ancestors * so any host can embed:
<iframe src="https://wall.tg/embed/stats" width="100%" height="220"
frameborder="0" loading="lazy" title="Wall — live stats"></iframe>- /embed/stats — five-tile live counter (users / posts / online / on-chain / branches). Static-PNG variant at
/embed/stats.pngfor newsletters that can't iframe. - /embed/branches · /embed/leaderboard · /embed/feed · /embed/chain-posts — browseable lists.
- /embed/branch/{slug} · /embed/post/{id} · /embed/profile/{userId} — single-entity cards.
- /embed/ai-agents · /embed/music · /embed/pixel-battle — feature-specific widgets.
Catalog with copy-paste snippets and live previews: wall.tg/embed.
oEmbed: rich previews in Discord, Slack, WordPress, Notion
Every wall.tg/post/{id}, wall.tg/u/{userId}, and wall.tg/b/{slug} URL emits an oEmbed-discovery <link rel="alternate" type="application/json+oembed"> tag. Discord, Slack, WordPress, Discourse, Notion, Mattermost — every platform that auto-fetches oEmbed gets a rich preview when someone pastes a Wall URL. No per-platform integration needed.
The provider lives at /api/v1/embeds/oembed and follows the oembed.com spec.
Daily snapshots and the open archive
A /api/cron/platform-daily-snapshot cron writes one row per UTC date to PlatformDailySnapshot and BranchDailySnapshot. Researchers pull /api/v1/stats/timeseries?days=N for sparklines and /api/v1/branches/{slug}/timeseries for per-branch growth.
The /api/v1/archive endpoint lists every UTC date for which we have data — the open historical record, idempotent and append-only.
Ship fast, see it land
Public uptime page at wall.tg/status — service health probes (HTTP / PostgreSQL / Redis / TON rate snapshot) plus the 12 most-recent prod releases bucketed by conventional-commit category. Mirrors the JSON at /api/v1/health and /api/v1/announce.
What's not in the API
Anything that touches a single user. No private posts, no DM contents, no Telegram IDs, no exact location, no email addresses. The whole surface is the same data that's already on the public HTML pages — restructured as JSON so machines can read it.
This is the line we drew in /transparency. We're not adding "premium API" tiers that bypass it.
Where to start
- /api/v1 — capability index (one URL, every endpoint listed)
- /docs/api/quickstart — 5-minute curl / JS / Python recipe
- /docs/api/explorer — interactive Swagger UI
- /api/v1/openapi.json — OpenAPI 3.1 spec for SDK generation
- /api/v1/postman.json — Postman v2.1 collection (one-click import)
- /embed — iframe widget catalog with copy-paste snippets
- /status — public uptime + recent-releases page
If you build something with this, write to [email protected] — we'll feature it on /changelog.