Skip to main content

​
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: 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 connection table).

​
Recipes

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

​
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.
Never print, log, or store private keys, license keys, or API keys in generated code or chat. Read them from environment variables.