Skip to main content

​
What this is

BLOOD v3 is a desktop/CLI trading bot. When it runs, it exposes two interfaces you can build on — without needing BLOOD’s source code:
  1. HTTP API — JSON over REST at http://<host>:50000/api/v1. Use it to control the bot (trades, tasks, wallets, presets, positions, …).
  2. NATS event stream — protobuf messages on subject bloodv3. Use it to watch what the bot does (swaps, task status, Polymarket orders, …).
You write your own program in any language that talks to those two interfaces. This section is adapted from the official build-on-blood Agent Skill that ships with BLOOD (skills/build-on-blood/SKILL.md in the release). Give it to an AI coding assistant so it can help you script, automate, and integrate with a running bot safely.

​
Use the skill with AI

The skill is a single markdown file in Agent Skills format (name + description frontmatter, then instructions the model follows).
1

Get the skill file

From your BLOOD release / install tree, open:
That file is the source of truth. This guide mirrors it for humans; keep the skill file next to your project when you want an AI to follow the same rules.
2

Load it in your AI tool

  • Claude Code / Agent Skills: copy or symlink the folder to .claude/skills/build-on-blood/ (so SKILL.md is inside that directory).
  • Cursor / other assistants: add the skill path to the agent’s skills/instructions, or paste / attach SKILL.md (or this guide section) into the chat / project rules.
  • Any chat: point the model at this docs section plus the OpenAPI reference so it has endpoints and shapes.
3

Ask for something concrete

Examples you can ask:
  • “Write a Go client that posts my detector txs to feed mode.”
  • “Script a one-shot buy on Solana using my wallet id and preset.”
  • “Subscribe to NATS SwapEvents and notify Discord on fills.”
  • “Run BLOOD headless on my VPS and drive it from a laptop.”
Keep BLOOD running (or --backend-only) so the AI can use real ids from GET /state, GET /wallets/, and GET /tasks/.
Money warning. The API moves real funds from real wallets. Never send a trade or start a task group unless you asked for that exact action. Confirm the wallet, token, direction, amount, and chain first. Never print, log, or store private keys, license keys, or API keys in code or chat — read them from environment variables.

​
Connection

Run headless with --backend-only, or set general.run.mode = 2 in config.toml. Exposing beyond localhost (general.run.backend.expose = true) is refused unless an API key or IP allowlist is set and NATS username and password are set. Do not expose the bot to the internet without those — prefer a VPN or SSH tunnel. See also VPS Setup.

​
Ready checks

  • GET /health → 200 when the process is up.
  • The bot must be initialised (POST /state) and have a valid license key before tasks or trades work. Check with GET /state.
  • Errors look like {"error": "message"} with status 400 (bad input), 404, 409 (conflict, e.g. duplicate name), or 500.
Base path for control calls: http://<host>:50000/api/v1/... (see API Getting Started — extra instances bump the port: 50000, 50001, …).

API flows

Endpoint map, one-shot trade, task groups, feed mode

Events & recipes

NATS events, build ideas, and safe working rules

API Getting Started

Base URL and OpenAPI reference

Feed mode

Task settings for bring-your-own-signal trades