> ## 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.

# Build on BLOOD

> Use the build-on-blood Agent Skill so AI assistants can help you automate BLOOD via HTTP and NATS.

## 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).

<Steps>
  <Step title="Get the skill file">
    From your BLOOD release / install tree, open:

    ```text theme={null}
    skills/build-on-blood/SKILL.md
    ```

    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.
  </Step>

  <Step title="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](/getting-started) so it has endpoints and shapes.
  </Step>

  <Step title="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/`.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

## Connection

| Thing | Default | Notes |
| - | - | - |
| HTTP | `localhost:50000` | Flags `--http-host`, `--http-port`. Port `0` disables it. |
| NATS (TCP) | `localhost:50010` | HTTP port + 10. Flags `--nats-host`, `--nats-port`. |
| NATS (WebSocket) | `localhost:50020` | HTTP port + 20. No TLS. |
| Auth (HTTP) | none locally | If the bot sets `api_key`, send header `X-API-Key: <key>` on every request; a wrong key gives `401` with no body. |
| Auth (NATS) | none locally | Username/password when the bot is exposed. |
| IP allowlist | off | `whitelisted_ips` in the bot config. Blocked callers are rejected. |

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](/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](/getting-started) — extra instances bump the port: `50000`, `50001`, …).

## Related pages

<CardGroup cols={2}>
  <Card title="API flows" icon="code" href="/build-api-flows">
    Endpoint map, one-shot trade, task groups, feed mode
  </Card>

  <Card title="Events & recipes" icon="bolt" href="/build-events-recipes">
    NATS events, build ideas, and safe working rules
  </Card>

  <Card title="API Getting Started" icon="rocket" href="/getting-started">
    Base URL and OpenAPI reference
  </Card>

  <Card title="Feed mode" icon="feed" href="/feed">
    Task settings for bring-your-own-signal trades
  </Card>
</CardGroup>


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