# Felix

> Non-custodial, paper-by-default trading infrastructure for AI agents.

Felix normalizes crypto, perps, options, stocks, and prediction markets through
one API. Sizes are USD. Funds remain in a client-owned wallet.

## Live resources

- Docs: https://felix.trade/docs
- OpenAPI: https://api.felix.trade/v1/openapi.json
- Swagger: https://api.felix.trade/v1/docs
- Status: https://api.felix.trade/v1/status
- Full agent reference: https://felix.trade/llms-full.txt
- Base URL: https://api.felix.trade

Browser chat and public self-service key issuance are coming after the API
launch. Initial manage keys are issued through controlled onboarding.

## Non-negotiable rules

1. Every API key starts with `fk_`; the prefix does not reveal paper/live mode.
2. Every order is paper by default, even with a live-enabled key.
3. Real execution requires an owner-authorized live key plus `paper:false`.
4. Use `Idempotency-Key` on every documented mutation. Reuse it only for an
   exact retry; after an ambiguous result, reconcile rather than changing it.
5. Owner private keys stay in the client wallet. Send signatures or exact signed
   requests only.
6. Raw API keys are shown once. Never put keys, signatures, signed transactions,
   or intent tokens in prompts, logs, feedback, screenshots, or source control.
7. A `429` is a temporary throttle. Honor `Retry-After`; do not rotate the key.

## First safe flow

```text
GET  /v1/status
GET  /v1/instruments?q=bitcoin
GET  /v1/quotes/BTC
POST /v1/orders/preview  {instrument:"BTC",side:"buy",size_usd:10}
POST /v1/orders          {instrument:"BTC",side:"buy",size_usd:10}
GET  /v1/positions
POST /v1/positions/{position_id}/close  + Idempotency-Key
GET  /v1/pnl
```

The order above is simulated because `paper:false` is absent.

## Programmatic accounts and keys

An existing `manage` key may create an isolated child:

```text
POST /v1/accounts + Idempotency-Key
{accept_terms:true,label:"agent"}
```

The first success returns a one-time paper key. Exact retries are redacted.
Discover children with `GET /v1/accounts` and keys with `GET /v1/keys`.

Mint paper keys with `POST /v1/keys/paper`. Live keys require
`/v1/keys/live/prepare`, client `personal_sign`, then `/v1/keys/live/submit`.
The signed message binds scopes, order cap, daily notional cap, daily-loss cap,
nonce, and expiry.

## Market signing

Generic live crypto/perp/options execution uses `POST /v1/orders` with
`paper:false`. Live prediction-market orders require the explicit client flow:

```text
POST /v1/orders/polymarket/prepare
client signs and posts the exact prepared request
POST /v1/orders/polymarket/checkpoint
POST /v1/orders/polymarket/commit
GET  /v1/orders/polymarket/intents/{intent_id}
```

## SDKs and MCP

- Python launch artifact: `felixtrade` (`from felix import Felix`)
- TypeScript launch artifact: `felix-sdk` (`import { Felix } from "felix-sdk"`)
- MCP package: `felix-mcp`, configured with `FELIX_API_KEY` (launch candidate;
  npm publication follows final dogfood)

The SDK and MCP package names are not public-registry install targets until
launch publication completes.

Non-custodial infrastructure, not a brokerage or financial advice.