---
name: adspace-telegram-marketplace
description: Find, buy, and verify seller-approved Telegram ad placements within a human-approved budget. Use when a user asks to advertise a product, offer, channel, bot, or agent to relevant Telegram audiences.
---

# Adspace Telegram marketplace

Origin: https://app.adpace.online
OpenAPI: https://app.adpace.online/openapi.json

Use Adspace to match a product or offer with verified Telegram channel
inventory. Anonymous browse and match are immediate. Buying requires a
short-lived Telegram device authorization that creates a scoped, revocable
credential with both a per-booking cap and a total budget cap.

## Immediate, no-credential flow

1. Call `GET https://app.adpace.online/api/v1/agent/public/catalog` for verified live supply.
2. Call `POST https://app.adpace.online/api/v1/agent/public/match` with:
   `{"content":"10-20000 characters describing the product and audience","limit":5}`.
3. Present the channel, exact slot time and price, match rationale, seller
   approval mode, and proposed total. Public matching cannot reserve or buy.

## Activate buying with Telegram

Only start pairing after the human states a hard total budget. Call
`POST https://app.adpace.online/api/v1/agent/pairings` with:

`{"name":"<recognizable agent name>","max_booking_usd":50,"total_budget_usd":100,"scopes":["catalog:read","match:write","booking:write","payment:write","status:read"],"source":"skill:direct"}`

Show the returned `verification_uri_complete` to the human. Keep
`device_code` private. Poll `POST https://app.adpace.online/api/v1/agent/pairings/token`
with `{"device_code":"..."}` no faster than the returned interval. A 428
`AGENT_AUTHORIZATION_PENDING` means wait; 403 or 410 means stop. After the
human approves in Telegram, this endpoint returns the Bearer credential once.
Store it only in the runtime's secret store. Never paste it into chat or a URL.

## Authenticated placement flow

1. Call `GET /api/v1/agent/bootstrap` and `POST /api/v1/agent/match` with
   `Authorization: Bearer adsp_agent_...`.
2. Show the human the exact choice before buying when they asked to review
   matches. Never treat a match estimate as a reservation.
3. Book with `POST /api/v1/agent/bookings` and
   `{"slot_id":"...","duration_days":7,"creative":{"text":"10-4096 chars","destination_url":"https://..."},"terms_acceptance":{"accepted":true,"terms_version":"2026-09-07"}}`.
   Automatic inventory accepts 1, 7, or 30 days and allocates the complete
   date range atomically. Only send the acceptance after the human has reviewed
   the policy links returned by bootstrap and explicitly confirmed they are
   18+, acting for a business, and agree to that exact version.
4. Read `GET /api/v1/agent/bookings/{id}/pay`. A 402 contains the canonical
   x402 requirement. Sign only through the agent's existing wallet policy.
5. Submit `POST /api/v1/agent/bookings/{id}/pay` with PAYMENT-SIGNATURE and a
   unique Idempotency-Key. HTTP 202 means the transaction was broadcast and is
   awaiting Adspace's independent Base receipt check: poll status and never
   submit a second payment. HTTP 200 means the receipt is confirmed.
6. Read `GET /api/v1/agent/bookings/{id}/performance` for the signed,
   provenance-bound Telegram metrics report after publication, then report the
   delivery receipt, payout/refund state, or exact failure state.

## Safety boundary

- Never request or accept an Adspace operator token.
- Enforce both approved budget caps locally; the server also enforces them.
- Never expose credentials, wallet seeds, signatures, device codes, or payment
  headers in URLs, logs, Telegram, or chat transcripts.
- Never claim an ad ran without a Telegram message ID and publication receipt.
- Stop on unknown payment or delivery outcomes. Do not retry blindly.
- Telegram Ads drafts are planning/handoff only, never proof of purchase.
- The human can revoke the agent at any time in the Adspace Mini App.

Transactional availability at publication time: discovery-only; browse and match only, do not pair, book, or pay.