# Ylalo
> Trading API built for AI agents. Stocks, bonds, crypto, and event markets through MCP or REST.
> Currently SANDBOX with play money. Agents can trade; agents cannot withdraw.
> API 0.6.0 · limitsVersion 2 · onboarding credit ~$50 USD when grants are on.

## Start here
- MCP (streamable HTTP): https://sandbox.ylalo.com/mcp  ·  Install: https://sandbox.ylalo.com/docs/mcp.md
- REST: https://sandbox.ylalo.com/v1  ·  OpenAPI: https://sandbox.ylalo.com/v1/openapi.json  ·  Agent bootstrap: GET /v1/start
- Agent card: https://sandbox.ylalo.com/agent.json  ·  Quickstart: https://sandbox.ylalo.com/docs/quickstart.md  ·  Full docs: https://sandbox.ylalo.com/llms-full.txt

## Auth
- Sandbox key (no phone, this host): POST /v1/sandbox/accounts
- Scoped agent keys (ylk_…): POST /v1/keys after phone OTP
- Phone OTP for humans: POST /v1/auth/otp → POST /v1/auth/verify
- OAuth device flow (partial): POST /v1/oauth/device → POST /v1/oauth/device/token
- Send Authorization: Bearer <key>. Never put keys in chat or code; use env var YLALO_API_KEY.

## Core docs
- [Orders, brackets, limit](https://sandbox.ylalo.com/docs/orders.md) · [Guardians / dead-man](https://sandbox.ylalo.com/docs/guardians.md)
- [Limits](https://sandbox.ylalo.com/docs/limits.md) · [Errors](https://sandbox.ylalo.com/docs/errors.md) · [Idempotency](https://sandbox.ylalo.com/docs/idempotency.md)
- [Market data](https://sandbox.ylalo.com/docs/market-data.md) · [Events](https://sandbox.ylalo.com/docs/events.md) · [Conventions](https://sandbox.ylalo.com/docs/conventions.md)
- [Auth](https://sandbox.ylalo.com/docs/auth.md) · [MCP install](https://sandbox.ylalo.com/docs/mcp.md) · [Changelog](https://sandbox.ylalo.com/v1/changelog)

## Rules for agents
- Confirm size, side and leverage with the user before placing orders. Prefer attaching a stop or guardian.
- Tell users plainly: leveraged products, sandbox, liquidation risk. Use stocks/bonds/portfolio/NAV language.
- Prefer clear risk language; you may name the execution venue when helpful.
- Check GET /v1/changelog when behaviour seems off.
- Prefer POST /v1/orders/suggest then POST /v1/orders (or ylalo_suggest_order / ylalo_place_order). Use Idempotency-Key on writes.
- Dead-man / guardians: POST /v1/guardians + POST /v1/heartbeat so protection continues while the agent sleeps.
- Sandbox available on this host: POST /v1/sandbox/accounts.

## Copy-paste prompt
```
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.
```

## Optional
- Status: https://sandbox.ylalo.com/status · Fees: https://sandbox.ylalo.com/fees · Privacy: https://sandbox.ylalo.com/privacy · Risk: https://sandbox.ylalo.com/risk
- security.txt: https://sandbox.ylalo.com/.well-known/security.txt
- MCP server card: https://sandbox.ylalo.com/.well-known/mcp/server-card