> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bloodydash.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Events & recipes

> NATS event stream, build recipes, and safe working rules for AI-assisted integrations.

## Watching events (NATS)

Connect with any NATS client to:

* TCP: `nats://<host>:50010` (default = HTTP port + 10)
* WebSocket: `ws://<host>:50020` (HTTP port + 20, no TLS)

Subscribe to subject **`bloodv3`**.

Each message is a protobuf `blood.events.v1.Event` defined in `proto/blood/events/v1/events.proto`, with one of:

| Event | Useful fields |
| - | - |
| **TaskEvent** | `group_id`, `task_id`, `status` (`started` / `completed` / `failed` / `info` / `warning` / `error` / `success`), optional `message` |
| **SwapEvent** | `transaction_id`, `slot`, `wallet_id`, `pool_id`, `platform`, token in/out info and amounts, `mcap_usd`, `tx_fee`, `tx_tip`, `tx_slippage_bps`, `mode`, `chain`, `strategy_id`, `preset_id`, `copy_trade_wallet`, `swap_settings` |
| **GenericEvent** | title, description, key/value fields — fields marked `is_sensitive` must **not** be forwarded to third parties |
| **PolymarketOrderEvent** | `order_id`, `token_id`, `is_buy`, `price`, … |

Generate language bindings from the `.proto` (`buf generate` or `protoc`). Timestamps use `created_at_nanos` (Unix nanoseconds).

When the bot is exposed beyond localhost, NATS expects username/password (see [Build on BLOOD](/build-on-blood) connection table).

## Recipes

Ideas the `build-on-blood` skill is meant to help you (or an AI) implement:

| Recipe | Approach |
| - | - |
| **Trade bot from a signal** | Subscribe to your data source → `POST /feed` (or `/trade/`) per signal → confirm fills with `SwapEvent`s |
| **Dashboard / PnL tracker** | Poll `GET /positions/` (`pnl`, `stable_profit_usd`, `shitcoin_left_percentage`) and listen to `SwapEvent`s |
| **Notifier** | Forward `TaskEvent` failures and `SwapEvent`s to Telegram / Discord |
| **Wallet ops** | `disperse` / `collect` to fan funds out to many wallets and sweep them back |
| **Remote control** | Run `--backend-only` on a VPS with an API key **plus** an IP allowlist, and drive it from a laptop or a bot |

## Working rules

Follow these whenever you or an AI write against the API:

1. **Read before write.** Call `GET /state`, `GET /wallets/`, `GET /tasks/` first, and use **real** ids from the responses. Never invent wallet, group, or preset ids.
2. **Dry-run first.** Prefer the smallest amount on the chosen wallet, and show the exact request JSON before sending anything that trades.
3. **Handle failure.** Treat non-2xx responses as failures and surface `error`. Do **not** retry `/trade/` or `/feed` blindly — a timeout does not mean the call did not execute. Check `GET /positions/` or the event stream first.
4. **Timeouts.** The server times out at **30s**. Set client timeouts a little above that for trades.
5. **Secrets.** Keys, license, and node credentials come from env vars or a secrets manager. Do not commit them. Wallet creation (`POST /wallets/`) takes a `private_key` — send it only over localhost or a private tunnel.
6. **API stability.** The API is versioned `v1` (spec version `0.0.1`). Pin to the bot version you tested against and re-read the OpenAPI spec after updating BLOOD.
7. **Stay in scope.** Do not build tools that bypass BLOOD's licensing, or that expose a user's bot to the public internet.

<Warning>
  Never print, log, or store private keys, license keys, or API keys in generated code or chat. Read them from environment variables.
</Warning>

## Related pages

* [Build on BLOOD](/build-on-blood) — skill install + connection
* [API flows](/build-api-flows) — endpoints and trade / task / feed calls
* [API Getting Started](/getting-started) — base URL
* [VPS Setup](/vps-setup) — running remotely
* [Positions (GUI)](/positions-gui) / [Positions (CLI)](/positions-cli)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.