Telegram and limit routes

Bind a human owner's chat, and cap what an agent may spend

Start a Telegram link

POST/v1/telegram/link/start

Mint a code and deep link for a human to confirm in Telegram.

Responses

Confirm a Telegram link

POST/v1/telegram/link/confirm

Consume a code the bot minted, binding that chat to your wallet.

Request Body

application/json

codeRequired

string

Required and non-empty.

Responses

Telegram link status

POST/v1/telegram/link/status

Check whether your wallet has a linked Telegram chat.

Responses

Remove a Telegram link

POST/v1/telegram/link/unlink

Remove the Telegram link.

Responses

Set spending limits

POST/v1/spending-limits

Set your spending caps for one chain.

Request Body

application/json

chain_idRequired

integer

Validated against the chains this server actually runs.

per_tx_cap_usdc

integer | null

null leaves that dimension unlimited, or clears it.

daily_cap_usdc

integer | null

total_cap_usdc

integer | null

Responses

Get spending limits

GET/v1/spending-limits

Get your spending caps for one chain.

Query Parameters

chain_idRequired

integer

REQUIRED here, unlike everywhere else on the surface. There is no default.

Example8453

Responses

Next steps

Telegram and intent tools — the tool twin, which carries a TelegramLinkCommitment where these routes use request signing
Identity and commitments — the owner wallet these six routes key on
The API — request signing, and what it does and does not prove

Telegram and limit routes

Start a Telegram link

Responses

200OK

401`unauthorized` — no recovered caller address in context.

404Returned by all four Telegram routes when the deployment has no Telegram stack — the same status a mistyped path returns, so a `404` here is not evidence the path is wrong.

500`mint failed`.

Confirm a Telegram link

Request Body

Responses

200OK

400`code required`, or `invalid or expired code`. Those three causes — not found, expired, already used — are deliberately one message: distinguishing them would turn this route into a way to test whether a code exists.

401`unauthorized`.

404Returned by all four Telegram routes when the deployment has no Telegram stack — the same status a mistyped path returns, so a `404` here is not evidence the path is wrong.

Telegram link status

Responses

200OK

401`unauthorized`.

404Returned by all four Telegram routes when the deployment has no Telegram stack — the same status a mistyped path returns, so a `404` here is not evidence the path is wrong.

500`status failed`.

Remove a Telegram link

Responses

200OK

401`unauthorized`.

404Returned by all four Telegram routes when the deployment has no Telegram stack — the same status a mistyped path returns, so a `404` here is not evidence the path is wrong.

500`unlink failed`.

Set spending limits

Request Body

Responses

200OK

400`invalid body`, `chain_id not configured`, or `caps must be non-negative`.

401`unauthorized`.

500`upsert failed`.

Get spending limits

Query Parameters

Responses

200OK

400`chain_id required`, `invalid chain_id`, or `chain_id not configured`.

401`unauthorized`.

404`no spending limit set` — a normal state, not a fault.

500`get failed`.

Next steps