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

# API flows

> HTTP endpoint map and core flows: one-shot trade, task groups, and feed mode.

Authoritative request/response shapes live in the OpenAPI spec the bot ships with (`docs/swagger.json` in the repo, generated with `make swagger`). Prefer generating a typed client from that spec. The interactive reference is also in this guide under [ADDONS → API](/getting-started).

## Endpoint map (`/api/v1`)

| Area | Endpoints |
| - | - |
| Health / state | `GET /health` · `GET /state` · `POST /state` (init) · `POST /state/license-key` · `GET /state/update` |
| Trade (one-shot) | `POST /trade/` · `POST /polymarket/trade` · `GET /polymarket/{wallet_id}/positions` |
| Tasks | `GET /tasks/` · `PUT /tasks/` (create group) · `POST /tasks/` (register modules) · `POST /tasks/idle` · `POST /tasks/{group_id}` (start) · `PUT /tasks/{group_id}` (stop) · `PATCH /tasks/{group_id}` (rename) · `DELETE /tasks/{group_id}` · `PATCH` / `DELETE` `/tasks/{group_id}/{task_id}` |
| Wallets | `GET` / `POST` `/wallets/` · `POST /wallets/disperse` · `/collect` · `/wrap` · `/unwrap` · `GET /wallets/{wallet_id}/balance` · `POST /wallets/{wallet_id}/upgrade` · `PATCH` / `DELETE` on groups and wallets |
| Positions | `GET /positions/?status=` · `GET /positions/{id}` · `POST /positions/refresh` · `/copy-trade-refresh` · `/{id}/hide` · `/{id}/activate` · `/{id}/delete` |
| Config | `GET` / `PUT` `/config` · `GET /config/comments` |
| Presets | `GET` / `POST` / `PUT` `/presets/` · `GET /presets/comments` · `PATCH` / `DELETE` `/presets/{id}` |
| Strategies | `GET` / `POST` `/strategies/` · `PUT` / `PATCH` / `DELETE` `/strategies/{id}` |
| Whitelist / blacklist | `GET` / `POST` / `DELETE` `/wlbl` · `GET` / `DELETE` `/wlbl/{group_id}` · `DELETE /wlbl/{group_id}/{wallet_id}` |
| Feed | `POST /feed` |
| Market making | `GET /mm/` (active groups) · `POST /mm/{id}/zip-out` (sell everything, then stop) |

## One-shot trade

```http theme={null}
POST /api/v1/trade/
Content-Type: application/json

{
  "wallet_id": "<id>",
  "chain": "solana",
  "input": "<token mint or address>",
  "direction": "buy",
  "amount": "0.1",
  "stable": "",
  "preset": "<preset id>",
  "strategy": "",
  "fee": 0,
  "tip": 0,
  "slippage": 0
}
```

* **Required:** `wallet_id`, `input`, `direction`, `amount`.
* `direction` is `buy` or `sell`. **Any other value silently becomes `buy`** — validate it yourself.
* `chain`: `solana` (default when empty/invalid), `evm`, `robinhood`. `input` is validated per chain (Solana base58 pubkey; EVM hex address).
* `preset` / `strategy` reference saved ids; `fee`, `tip`, `slippage` are per-call overrides.
* EVM / Robinhood wallets must be **upgraded** first: `POST /wallets/{id}/upgrade`.
* Response includes `task_id` and, when finished, `result` (`transaction_id`, `slot`, `pool_id`, `pool_platform`, `token_in` / `token_out` info, amounts, `market_cap_usd`).

<Note>
  Exact semantics of `amount` and `stable` (which token, what units) are not fully spelled out in the OpenAPI spec. Test with a tiny amount — or confirm with the user — before scaling up. For asset tickers and empty-stable behavior, see [Assets](/assets).
</Note>

### Polymarket trade

`POST /polymarket/trade` with:

| Field | Notes |
| - | - |
| `wallet_id` | Required |
| `token_id` | Outcome token |
| `direction` | `buy` or `sell` |
| `size` | USDC for buys, shares for sells |
| `price` | Optional, 0–1; market price if omitted |
| `slippage` | Optional, 0–100 |

Also: `GET /polymarket/{wallet_id}/positions`.

## Task groups (long-running automation)

**Modules:** `solswap`, `evmswap`, `polymarket`, `dtf`, `solmm`.

Solswap modes include default, copy-trade, afk, limit, snipe, feed, and bb.

1. `POST /tasks/` once to **register** task modules after init.
2. `PUT /tasks/` to create a group:

   ```json theme={null}
   {
     "id": "<group name>",
     "module": "solswap",
     "data": []
   }
   ```

   `data` is an array of task models for that module. Shape depends on the module — copy an existing group from `GET /tasks/`, or read `models.Task` / `models.<Module>Metadata` in the OpenAPI spec.
3. `POST /tasks/{group_id}` to **start**, `PUT /tasks/{group_id}` to **stop**. `POST /tasks/idle` starts all idle groups.
4. Change a running setup with `PATCH /tasks/{group_id}/{task_id}` rather than deleting and recreating.

Task settings are large. Prefer creating a **preset** (`POST /presets/` in the GUI or via API) and referencing it instead of hand-writing every field. `GET /presets/comments` and `GET /config/comments` return field-by-field documentation — use those to explain settings instead of guessing.

Related guide pages: [Presets (CLI)](/preset-cli), [Presets (GUI)](/presets-gui), [Strategies](/strategies-cli), [Tasks (CLI)](/tasks-cli).

## Feed mode (bring your own signal)

`feed` mode tasks fire when **you** push a Solana transaction. Use this to trigger buys from your own detector. Task field reference: [Feed](/feed).

```http theme={null}
POST /api/v1/feed
Content-Type: application/json

{
  "transaction": "<base64 tx>",
  "slot": 123456789,
  "ctx": {
    "group_id": "<group>",
    "task_id": -1,
    "amount": "0.05",
    "fee": 0,
    "tip": 0,
    "slippage": 0
  }
}
```

* `transaction` is a base64 Solana transaction and is the **only required** field. With no `ctx`, all running feed tasks see it.
* With `ctx`, `group_id` is required. `task_id: -1` targets all tasks in the group; `amount` / `fee` / `tip` / `slippage` override per call.
* Leave `no_account_set_on_create_pool` unset unless BLOOD maintainers tell you to set it.
* Working reference clients ship in the repo at `examples/feed/go` and `examples/feed/rust`.


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