API reference · Neo24 Block Watcher

API reference
Agent prompt Paste this into your AI agent. It already knows Neo24, then builds the integration in your app.
You are integrating Neo24 (https://neo24.net) into this codebase. Neo24 watches blockchain addresses and reports incoming financial transfers: native coins and fungible tokens. NFTs are out of scope. Do not invent endpoints.

Base URL: https://api.neo24.net
Auth header: Authorization: Bearer {SANCTUM_TOKEN}
The user creates the Sanctum token in the Neo24 Users panel. The account email must be verified. Abilities: me:read, blockchains:read, addresses:read, addresses:write, matches:read, ws:connect. A token with * can call every route. Tokens do not expire unless the user set an expiry when creating the token. transactions:read is an alias of matches:read.

Read first:
- GET /me — plan and address cap
- GET /blockchains — active chains (page, per_page; default 50, max 200). {blockchain} on GET /blockchains/{blockchain} is a numeric id or a slug.
- POST /addresses — body needs address plus blockchain_id or blockchain_slug. Optional name and is_active. 201 returns the watched address.
- PATCH /addresses/{id} updates only name and is_active. DELETE /addresses/{id} stops watching it.
- GET /matches and GET /addresses/{id}/matches use cursor pagination: limit (default 50, max 200) and cursor. Pass meta.next_cursor back as cursor. Newest match id first. The page is {data, meta: {next_cursor, has_more, limit}}. Each item is {id, address_id, block, txid, transfer_index, from_address, amount, asset, type, count, blockchain: {id, slug, name}, address: {id, address, address_display}, created_at}. amount is a decimal string. asset null means the chain native coin.

Every live event, whether WebSocket or webhook, has this JSON shape:
{"type":"incoming_payment","match_id":123,"fields":{"chain_slug":"bnb","chain_name":"BNB Mainnet","address":"0x…","amount":"1.0","asset":"native","txid":"0x…","block":"100","type":"coin"}}
amount is a decimal string. asset null or "native" means the chain's native coin.

WebSocket (client receives only; it does not publish matches):
- The user must add a WebSocket destination in the Neo24 Users panel or nothing is published.
- POST /ws/connection with ability ws:connect and no body. Response fields: token (Centrifugo JWT, not the Sanctum token), ws_url, channel, expires_at (unix seconds), history_size (default 200), history_ttl (default 2h). 503 means WebSocket delivery is disabled.
- Connect to ws_url with that JWT. Subscribe to channel with {recoverable:true}. On a brand-new connection with no recovered offset, call subscription.history({limit: history_size}). Before expires_at, call POST /ws/connection again and return the new token from the Centrifugo client's token callback (getToken). Reconnect only if the socket has already closed.
- Use the centrifuge client for the host language. Publication data is the incoming_payment object above.

Webhook (Neo24 calls the user's HTTPS URL):
- The user saves the URL and a signing secret of at least 16 characters in the Neo24 Users panel. This API does not create webhook destinations. The URL must be HTTPS and must resolve to a public address.
- Neo24 POSTs the same incoming_payment JSON. Headers: Content-Type application/json, User-Agent Neo24-Webhook/1.0, X-Neo24-Event incoming_payment, X-Neo24-Delivery-Id, X-Neo24-Signature sha256={hex}.
- The signature is HMAC-SHA256 of the raw request body using the signing secret, prefixed with "sha256=". Compare with a timing-safe equality check. Do not parse and re-encode the JSON before hashing.
- Respond with any HTTP 2xx within 10 seconds. Other statuses and timeouts retry up to 5 times, after 30s, 2m, 10m, and 30m. Redirects are not followed.

Implement only the delivery method the user asks for (poll matches, WebSocket, or webhook), in the style of this codebase. Ask for the Sanctum token if it is not already configured. Paths above are rooted at the base URL. Use only the fields named here.