API and agents

Everything you do on the Watchdog page is also available under /api/x402: list and create watches, change signals and routing, manage recipients and send tests, read and export the alert history, get prices, buy slots and top up credits. Changes made through the API show up in the app immediately, and the other way round.

A machine signs in with the wallet, not with a password. The flow takes five steps:

1. POST /api/x402/auth/challenge with the wallet address, the requested scopes and an optional name for the token.
2. The answer contains a sign-in message in the SIWE format (EIP-4361). It is valid for 5 minutes and lists the requested scopes.
3. The wallet signs the message. Smart-contract wallets that support EIP-1271 work too.
4. POST /api/x402/auth/token with the message and the signature.
5. The answer contains a token starting with fbx_ and its expiry, 24 hours by default. The machine sends it in the header Authorization: Bearer.

The token is shown only in that answer. Store it like a password.

• read is always included: reading watches, recipients, alerts, prices and the account.
• write allows changes: creating and editing watches, recipients and settings.
• spend allows actions that use credits, such as buying slots.

Examples: a dashboard that only shows alerts needs read. A bot that sets up watches for new team members needs read and write. An agent that also buys slots on its own needs read, write and spend. If a scope is missing, the API answers 403 with the code insufficient_scope and names the required scope.

All tokens of your wallet are listed in Account Settings → API access, with name, creation date, expiry and last use. Revoke stops a token immediately; this cannot be undone. A wallet can have at most 10 active tokens at the same time. Machines can revoke a token themselves with DELETE /api/x402/auth/tokens/{id}.

Requests that create something or cost credits need the header Idempotency-Key, a value of 8 to 128 letters, digits, _ or -. If the connection drops, the machine sends the same request with the same key again and gets the first result, instead of paying twice. The same key with a different request is rejected with idempotency_key_reused.

If a watch needs a slot or the balance is too low, the API answers 402. The answer contains the code slot_required or insufficient_credits, a ready purchase suggestion and the endpoint for topping up. An agent can then decide on its own, or ask you first.

• OpenAPI description of all operations, including scopes and error codes.
• Webhook schema v2 for the alerts your webhook receives.
• llms.txt as a short entry point for language models.
• API catalog according to RFC 9727.
• API documentation for people, with code examples.

A server for the Model Context Protocol, which AI assistants can connect to directly, is planned but not available yet. Until then, agents use the HTTP API described above.