# Ylalo full docs
> Concatenated markdown docs for agents.
> Source: /docs/*.md


---

# /docs/quickstart

# Quickstart

Ylalo is a **trading API for AI agents**. **www.ylalo.com is MAINNET (real funds)**. Demo sandbox is https://sandbox.ylalo.com (play money). Agents can trade; agents cannot withdraw.

## Copy-paste prompt for your agent

```
Set me up to trade on Ylalo.
1. Read https://www.ylalo.com/llms.txt and GET /v1/start. Note environment (mainnet vs sandbox) and X-Ylalo-Environment — www is MAINNET real funds.
2. Connect MCP at https://www.ylalo.com/mcp (or REST /v1, OpenAPI /v1/openapi.json).
3. Auth on www/mainnet: phone OTP then POST /v1/keys. Store as YLALO_API_KEY, never in chat. For phone-free play money use the demo host https://sandbox.ylalo.com → POST /v1/sandbox/accounts (never call sandbox on www).
4. Show balance and limits (GET /v1/account). Attach a dead-man or stop guardian if you may sleep. Tell me plainly: leveraged products, environment, liquidation risk.
5. Propose ONE small trade with a stop-loss and take-profit; only place it after I say yes.
6. Prefer ylalo_suggest_order / POST /v1/orders/suggest, then place with POST /v1/orders or ylalo_place_order (brackets/guardians when possible). Do not use /v1/perps/*.
7. Use stocks/bonds/portfolio/NAV language with users. Prefer clear risk language; you may name the execution venue when helpful.
```

## curl (mainnet / www — OTP + key)

```bash
curl -s -X POST https://www.ylalo.com/v1/keys -H "authorization: Bearer $YLALO_SESSION" \
  -H 'content-type: application/json' -d '{"name":"my-bot"}' | tee ylalo.json
export YLALO_API_KEY=$(jq -r .apiKey ylalo.json)

curl -s https://www.ylalo.com/v1/account -H "authorization: Bearer $YLALO_API_KEY"

curl -s -X POST https://www.ylalo.com/v1/orders/suggest -H "authorization: Bearer $YLALO_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"market":"BTC","side":"long","usdAmount":25,"leverage":5}'
```

Confirm the suggest plan with the user, then `POST /v1/orders` (or dryRun → confirm) with brackets/guardians and an `Idempotency-Key` header.

## Sandbox (https://sandbox.ylalo.com only)

`POST https://sandbox.ylalo.com/v1/sandbox/accounts` — phone-free play money. Not available on www.

## MCP

- Endpoint: `https://www.ylalo.com/mcp`
- Install: [MCP install guide](./mcp.md)
- Bootstrap: `GET /v1/start` or tool `ylalo_start`

## Next

- [Auth](./auth.md) · [Orders](./orders.md) · [Errors](./errors.md) · [llms.txt](/llms.txt)


---

# /docs/mcp

# MCP install

Streamable HTTP endpoint: `https://www.ylalo.com/mcp`

## Cursor

[Add to Cursor](https://cursor.com/en/install-mcp?name=ylalo&config=eyJ1cmwiOiJodHRwczovL3d3dy55bGFsby5jb20vbWNwIn0=)

Or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ylalo": { "url": "https://www.ylalo.com/mcp" }
  }
}
```

## Claude Code

```bash
claude mcp add --transport http ylalo https://www.ylalo.com/mcp
claude mcp add --transport http --scope project ylalo https://www.ylalo.com/mcp
```

## Claude.ai / Desktop

Settings → Connectors → Add custom connector → URL `https://www.ylalo.com/mcp`.

## ChatGPT

Settings → Connectors → enable Developer mode → Create → name **Ylalo**, auth **No authentication**, URL `https://www.ylalo.com/mcp`. Sign-in happens in-chat (phone OTP on mainnet).

## VS Code / Copilot

```bash
code --add-mcp '{"name":"ylalo","url":"https://www.ylalo.com/mcp"}'
```

## Auth inside MCP

1. Pass `Authorization: Bearer ylk_…` (or session token) from the MCP client when supported.
2. On **www / mainnet**: tools `ylalo_request_otp` / `ylalo_verify_otp`. `ylalo_start` does **not** create a sandbox account.
3. Sandbox accounts: REST only — `POST https://sandbox.ylalo.com/v1/sandbox/accounts` (not www).

GET `https://www.ylalo.com/mcp` in a browser returns this install guide (POST is JSON-RPC).


---

# /docs/auth

# Auth

## Sandbox (https://sandbox.ylalo.com, no phone)

Demo host: **https://sandbox.ylalo.com** (`NETWORK=sandbox`, `HL_NETWORK=testnet`). Not available on www.

```bash
curl -s -X POST https://sandbox.ylalo.com/v1/sandbox/accounts \
  -H 'content-type: application/json' -d '{"name":"my-bot"}'
# → { "apiKey": "ylk_test_…", "balanceUsd": "50", "environment": "sandbox", ... }
```

Rate-limited per IP. Store `apiKey` as `YLALO_API_KEY`. Never commit it or paste it into chat.

## Phone OTP (humans)

1. `POST /v1/auth/otp` with flexible `phoneNumber`
2. `POST /v1/auth/verify` with code + `nickname` (new users). May require `inviteCode` when invites are on.
3. Use returned `accessToken` as Bearer.

## Scoped agent keys

After a phone session: `POST /v1/keys` with `scopes: ["read","trade"]` and optional `maxExposureUsd`. Secret shown once.

## Header

`Authorization: Bearer <YLALO_API_KEY or accessToken>`

OAuth 2.1 for Claude.ai / ChatGPT one-click Connect is planned; use sandbox keys today.


---

# /docs/orders

# Orders

## Intent API

`POST /v1/orders` accepts USD-first intents. Prefer `POST /v1/orders/suggest` first. Do not use `/v1/perps/*`.

```json
{
  "market": "perp:BTC",
  "side": "long",
  "usdAmount": 45,
  "leverage": 10,
  "bracket": { "stopLoss": { "pct": -2 }, "takeProfit": { "pct": 4 } },
  "guardians": [{ "type": "max_hold", "seconds": 86400 }],
  "dryRun": true
}
```

When `dryRun: true`, response includes `planId`, `confirmToken`, and a human `summary`. Execute with `POST /v1/orders/confirm`.

## Suggest sizing

`POST /v1/orders/suggest` sizes an open/close to venue minimum and book depth.

## Close

`POST /v1/positions/{market}/close` with `{ "fraction": 0.5 }` or `{ "usdAmount": 20 }` or `{ "size": "…" }`.

## List & cancels

- `GET /v1/orders` — open + trigger orders
- `DELETE /v1/orders/{oid}` — cancel one
- `DELETE /v1/orders?coin=BTC` — cancel all for a coin

## Outcomes

`POST /v1/outcomes/trade` for prediction/event shares (no leverage).

Always confirm size, side, and leverage with the user before submitting (prefer `dryRun` → confirmToken).


---

# /docs/guardians

# Guardians & stops

Server-side protection so agents need not stay awake. Attach brackets on `POST /v1/orders` and/or create guardians via `POST /v1/guardians`. Heartbeat: `POST /v1/heartbeat`.

## Practice

1. Always propose protection with the first trade plan (`bracket` on `POST /v1/orders` and/or guardians).
2. After open, confirm guardians and resting triggers via `GET /v1/account` or `GET /v1/orders`.
3. On resume: `GET /v1/events?since=<lastEventId>` then `GET /v1/account`.


---

# /docs/market-data

# Market data

- `GET /v1/markets?query=BTC&asset_class=crypto`
- `GET /v1/markets/{coin}/candles?interval=1h`
- `GET /v1/markets/{coin}/book`

Public (no auth). Thin-market badges appear on search results — prefer `/v1/orders/suggest` before opening.


---

# /docs/limits

# Limits

- Platform default: **no** notional cap. Venue minimum notional still applies (~$10 perps).
- Optional self-limits: `GET/PATCH /v1/settings` (`maxTradeUsd`, `dailyTradeCapUsd`).
- API keys may set `maxExposureUsd`.
- See `limits` on `GET /v1/system/status`, `GET /v1/limits`, and `GET /v1/account`.
- `limitsVersion` is in `GET /v1/changelog`.


---

# /docs/errors

# Errors

JSON shape:

```json
{ "error": { "code": "insufficient_funds", "message": "…", "details": {} } }
```

| Code | What to do |
| --- | --- |
| `invalid_input` | Fix request body; see OpenAPI |
| `unauthorized` | Recreate sandbox key or re-verify OTP |
| `forbidden` | Wrong environment (e.g. sandbox on mainnet) or missing invite |
| `not_found` | Wrong path or id |
| `rate_limited` | Back off; honor `Retry-After` |
| `insufficient_funds` | Deposit / wait for grant; see `GET /v1/funding` |
| `limit_exceeded` | Lower size or raise settings caps |
| `service_unavailable` | Retry shortly; check `/status` |

Every failure should leave the agent with a next step (funding, suggest, or user confirm).


---

# /docs/idempotency

# Idempotency

Send `Idempotency-Key: <unique string>` on trade writes (`/v1/orders`, `/v1/orders/confirm`, close, outcomes, packages).

Replays with the same key + body return the original response. Change the body → treat as a new request with a new key.


---

# /docs/events

# Events

Poll `GET /v1/events?since=<lastEventId>` for what happened while the agent was away.

For fill history: `GET /v1/trades` / MCP `ylalo_get_trade_history`, plus positions on `GET /v1/account`.

Optional: `GET /v1/events/stream` (SSE) and `POST /v1/webhooks` for HMAC callbacks.


---

# /docs/conventions

# Conventions

- Quote: **USD** account value (quote currency is USD).
- Size: base asset units, not USD notional.
- Timestamps: unix seconds unless noted.
- Environment header: `X-Ylalo-Environment: sandbox|mainnet`.
- Books in product copy: main / stocks / events (eng: native / xyz / outcomes).


---

# /docs/changelog

# Changelog

Machine-readable: [`GET /v1/changelog`](/v1/changelog) and [RSS](/changelog.xml).

## 0.5.2 — 2026-10-19

- BREAKING: removed `/v1/perps/*`, legacy MCP perp tools; prefer `POST /v1/orders`
- `GET /v1/account`, `GET /v1/events`, guardians, honest mainnet labelling on www

## 0.5.1 — 2026-10-19

- `X-Ylalo-Environment` header; status.network is sandbox|mainnet

## 0.5.0 — 2026-10-19

- Agent-first discoverability: `/agent.json`, MCP server card, rewritten `/llms.txt`, friendly `GET /mcp`
- `POST /v1/sandbox/accounts`
- Environment labeling + `X-Ylalo-Environment`
- Multi-page docs with `.md` twins


---

# /docs/faq

# FAQ

**Is this real money?** On **www / mainnet**, yes — real funds. On **https://sandbox.ylalo.com**, no — play money. Check `X-Ylalo-Environment` and `GET /v1/system/status`.

**Can agents withdraw?** No.

**What settles trades?** Ylalo routes orders to its execution venue. Agents may name the venue when asked; prefer clear risk language.

**How do I start without a phone?** `POST https://sandbox.ylalo.com/v1/sandbox/accounts` (demo / play money). On www/mainnet use phone OTP then `POST /v1/keys`.

**Where is the MCP URL?** `https://www.ylalo.com/mcp`


---

# /docs/recipes/first-protected-trade

# Recipe: first protected trade

1. Auth: on www/mainnet phone OTP → `POST /v1/keys`; on https://sandbox.ylalo.com optionally `POST /v1/sandbox/accounts` → `YLALO_API_KEY`
2. `GET /v1/account` — confirm balance / limits
3. `POST /v1/orders/suggest` with small `usdAmount`
4. Show the plan to the user; wait for yes
5. `POST /v1/orders` with `dryRun: true` → `POST /v1/orders/confirm` with `Idempotency-Key`
6. `GET /v1/account` + `GET /v1/orders` — report armed stops / guardians
7. On resume: `GET /v1/events?since=<lastEventId>`