Create watch
POST
/v2.Watch/Create
one address; apiton reads it and stores an event for every change. An NFT item (username,
number,
.ton domain, gift, any NFT) is watched for its sale and auction, any other address forits transactions: the server decides which from what is on the chain.
Poll: read them with a cursor. No server needed. Every event is there for 7 days.webhook_url and apiton POSTs each event to your HTTPS endpoint, signed.Authorization: Bearer <tg_id>:<secret>. Without one the answer isunauthenticated. Each RPC costs one request of your plan; webhook deliveries cost none.A watch of another key answers
not_found. While the service is off on the server, every RPCanswers
unavailable.| Plan | Watches | Each address read every | Webhook pushes per hour |
|---|---|---|---|
| free, premium | 3 | 180 s | 10 |
| builder, pro | 30 | 30 s | 100 |
all. Premium has free's numbers here, as everywhere in the API; the bot's own Premium limits are
separate.
Poll and the hourly cap are per key; the cap is per clock hour (UTC) and applies towebhook pushes only: events above it are stored all the same, with delivery
capped.watches keep running at 180 s, the others are paused (
paused: true in List): they are notread for you and raise no events until the plan returns or you delete some. A paid plan takes
effect within about two minutes. A paused watch that resumes starts from the state it finds, and
does not report what happened while it was paused.
Delete frees a place at once.Create
| Field | Type | Notes |
|---|---|---|
address | string | any form (raw 0:…, EQ…, UQ…); mainnet only; no .ton names |
webhook_url | string | optional; see the rules below |
min_amount | number | optional, wallet watches, ≥ 0; default 1 |
curl -X POST https://app.apiton.org/v2.Watch/Create \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123456789:aB3dE…' \
-d '{"address":"UQCdqXGvONLwOr3zCNX5FjapflorB6ZsOdcdfLrjsDLt3AF4","webhook_url":"https://example.com/apiton","min_amount":1}'
# {"watch":{"id":"41","address":"UQCdqX…","kind":"wallet","name":"UQCdqX…3AF4","min_amount":1,
# "poll_interval_seconds":180,"created_at":"2026-11-02T12:00:00Z",
# "webhook":{"url":"https://example.com/apiton","state":"active"}},
# "webhook_secret":"whsec_9f2c…","created":true}webhook_secret is shown once, in this answer. Keep it: it signs your deliveries. It belongsto this watch and is not your API key.
created: false, no secret. To change a webhook_url or min_amount, Delete and Createagain (a new id, a new secret).
Create raises nothing: the watch starts from the state it finds.webhook_url must be https, on port 443 or 8443, on a public host, without user:password, upto 2048 characters. It is checked at
Create and again at every delivery, and the connection goesonly to public addresses resolved at that moment, so a name that later points at a private address
is refused. Redirects are not followed: a 3xx is a failed delivery.
unauthenticated no key · invalid_argument bad address, testnet address, or a refusedwebhook_url (the message says why) · resource_exhausted the plan's watch limit, with what thenext plan gives ·
failed_precondition a field out of its bounds, or the item was taken down ·unavailable the chain read failed or the service is off: retry.Webhook delivery
POST with Content-Type: application/json and:| Header | Value |
|---|---|
X-Apiton-Signature | sha256= + hex HMAC-SHA256 of <timestamp>.<body>, keyed with webhook_secret |
X-Apiton-Timestamp | Unix seconds of this attempt |
X-Apiton-Event-Id | the event's id |
ignored. If apiton restarts during a delivery, or your 2xx is lost, the event comes again with the
same
id: remember the ids you have processed and drop a repeat. Events of one watch go out inorder, and a failure holds back the ones behind it.
work ended.
belong to the webhook, not to the event: while it fails, its other events wait. After about 24
hours of failures it is
paused: its queue is dropped, new events go to Poll only, and nothingis pushed until a delivered
Test. What it missed is in Poll, from your last cursor, for 7 days.Status and last error are in
List.the JSON's spacing is not stable. Refuse a timestamp far from your clock, so that a captured
request cannot be replayed.
# body.json: the raw body; $TS: X-Apiton-Timestamp; $SECRET: webhook_secret
printf '%s.' "$TS" | cat - body.json | openssl dgst -sha256 -hmac "$SECRET"
# SHA2-256(stdin)= 43a1ae1376fc… must equal X-Apiton-Signature after "sha256="Request
Body Params application/jsonRequired