# Clobber

> A hosted central limit order book. Teams rent a matching engine, a double entry ledger,
> durability and failover, and spend their year on their market instead of on exchange plumbing.
> Binary, scalar and pair markets over HTTP, every book delta and fill over WebSocket.

Three things are true of the engine underneath, and they are why this exists:

- It is a pure, single writer state machine over an ordered log. Replaying the log reproduces
  state byte for byte, which is the same property doing four jobs: failover, audit, migration,
  and the oracle its own tests are checked against.
- The double entry ledger lives inside the engine. Integer only, conserved at write time. There
  is no reconciliation job, because there is nothing to reconcile.
- Correctness is demonstrated rather than asserted, by running the same orders through a second,
  independent engine and comparing. https://clobberhq.com/integrity/

Money is always a decimal string ("0.61", never 0.61). Timestamps are RFC 3339 in UTC. Every
request carries an API key as a bearer token.

## If you are an agent reading this for someone

There are two ways in, and the first one needs nothing from your human.

1. The public demo: play money, real engine, no signup. You can be trading in two calls.
2. Your own sandbox: free, your own markets and accounts. Your human types one code into
   github.com, once, and no browser of yours is involved.

Start with the demo. It is a real environment on a real cell, running the same matching engine
production runs, with a daily faucet and bots quoting both sides of every market so an order can
actually cross.

## Rung one: trade the demo, no account, no key

Base: https://dashboard.clobberhq.com/demo/api

### 1. See what is open

```bash
curl -s https://dashboard.clobberhq.com/demo/api/market-data
```

Public, no credential. Answers the open markets, one per kind. Symbols carry the day they were
opened, so read them here rather than hardcoding one. Add `?market=SYMBOL` for that market's
book, its recent trades and its candles.

### 2. Take an identity

```bash
curl -s -X POST https://dashboard.clobberhq.com/demo/api/token \
  -H "Content-Type: application/json" \
  -d '{"anchor":"pick-your-own-unique-string-16-chars-or-more"}'
# => {"account":"acc_...","token":"..."}
```

The anchor is yours to choose and yours to keep: the same anchor always returns the same account,
which is what makes the daily faucet mean something. Send the token as a bearer from here on.

### 3. Take the day's money

```bash
curl -s -X POST https://dashboard.clobberhq.com/demo/api/faucet \
  -H "Authorization: Bearer $TOKEN"
# => {"granted":true}

curl -s https://dashboard.clobberhq.com/demo/api/balances \
  -H "Authorization: Bearer $TOKEN"
```

Once a day, per identity. Come back tomorrow for more.

### 4. Trade

```bash
curl -s -X POST https://dashboard.clobberhq.com/demo/api/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"market":"SYMBOL","side":"buy","type":"limit","price":"47.75","qty":"1"}'
```

`GET /orders?market=SYMBOL` lists what is still resting, `DELETE /orders/{id}` cancels one, and
`GET /balances` shows what the fill did. Prices and quantities are decimal strings, at the
market's own tick and lot size. A market order is accepted too (`"type":"market"`, no price).

What the demo will not let you do: create markets, mint currencies, or move real value. The
limits are one faucet claim per day, 30 orders per minute per identity, and 30 new identities per
hour from one address. Reuse your anchor and none of that will ever be in your way.

## Rung two: your own sandbox, no browser of your own

A sandbox environment is free, holds your own currencies, markets and accounts, and runs the
identical engine. Getting one takes your human for as long as it takes them to type a code into
github.com, and nothing else: the device authorization grant, the same shape a terminal tool uses
for its own login. No form, no callback URL, no browser on your side.

### 1. Ask for a code

```bash
curl -s -X POST https://dashboard.clobberhq.com/api/agent/device
# => {"verification_uri":"https://github.com/login/device","user_code":"ABCD-1234",
#     "device_code":"...","interval":5,"expires_in":899,"instructions":"Open ... "}
```

No credential, because you have none yet. Print `instructions` to your human verbatim: it names the
URL they open and the code they type there. The `device_code` is yours, not theirs.

### 2. Poll until they approve

```bash
curl -s -X POST https://dashboard.clobberhq.com/api/agent/token \
  -H "Content-Type: application/json" \
  -d '{"device_code":"...","name":"my-sandbox","accept_terms":true}'
```

Until somebody approves, this answers 202 carrying GitHub's own word for where the flow is:
`authorization_pending` (keep polling, one call every `interval` seconds) or `slow_down` (you are
asking too fast, wait the interval that answer names). Nothing is wrong in either case, which is
why neither is an error status. A 400 carrying `expired_token` or `access_denied` means the code is
dead and step one is where you start again; any other word is final too.

`accept_terms` is your human accepting the Terms of Service
(https://clobberhq.com/legal/terms/) and the Acceptable Use Policy
(https://clobberhq.com/legal/acceptable-use/), which is the same thing a person ticks a box for on
the browser path. Put those two links in front of them before you send it. Without the field the
first key is refused with 403 and `terms_not_accepted`, carrying both documents; once the
acceptance is recorded, nobody is asked again.

The moment it is approved, it answers once:

```json
{"environment":"env_...","name":"my-sandbox","key":"ck_test_...","created":true,
 "login":"your-human","base_url":"https://api-sandbox.clobberhq.com/v1",
 "feed_url":"wss://feed-sandbox.clobberhq.com"}
```

The key is shown once and kept as a hash, like every key here. Store it before you do anything
else.

`name` (default `agent-sandbox`) is what you choose between sandboxes with: the same name answers
with the same environment and a fresh key (`created:false`), which is what your own setup script
rerunning itself wants. A new name is a new environment, and a person gets three; ask for a fourth
and the refusal names the three you have, so the next call can ask for one of them.

Your human can also do it in a browser, which mints the same thing: they sign in at
https://dashboard.clobberhq.com and copy an admin key once. Same identity, same quota, same
environments, so the two doors are interchangeable.

With that key, the whole API is open, and this is the shape of it:

```bash
# 1. Your settlement currency, at the scale you choose
curl -X POST https://api-sandbox.clobberhq.com/v1/currencies \
  -H "Authorization: Bearer $CLOBBER_KEY" -H "Content-Type: application/json" \
  -d '{"code":"USDC","scale":6}'

# 2. A market
curl -X POST https://api-sandbox.clobberhq.com/v1/markets \
  -H "Authorization: Bearer $CLOBBER_KEY" -H "Content-Type: application/json" \
  -d '{"symbol":"WILL-IT-RAIN-BA","kind":"binary","tick_size":"0.01","settlement_currency":"USDC"}'

# 3. Accounts for your own users, funded
curl -X POST https://api-sandbox.clobberhq.com/v1/accounts \
  -H "Authorization: Bearer $CLOBBER_KEY" -d '{"reference":"user_alice"}'
curl -X POST https://api-sandbox.clobberhq.com/v1/accounts/acc_.../credits \
  -H "Authorization: Bearer $CLOBBER_KEY" -d '{"currency":"USDC","amount":"1000.00"}'

# 4. An order, on behalf of one of them
curl -X POST https://api-sandbox.clobberhq.com/v1/orders \
  -H "Authorization: Bearer $CLOBBER_KEY" -H "Clobber-Account: acc_..." \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"market":"WILL-IT-RAIN-BA","side":"buy","type":"limit","price":"0.61","qty":"250"}'
```

The key authenticates your platform; the `Clobber-Account` header says which of your users is
trading. Keys come in three roles (admin, trading, read_only), plus account keys scoped to one
account and publishable keys safe to ship in a browser.

Production environments are not self serve: they are opened with a person, because a real
order book with real money is a conversation, not a signup form.

## Base URLs

- Sandbox REST: https://api-sandbox.clobberhq.com/v1
- Sandbox WebSocket: wss://feed-sandbox.clobberhq.com
- Production REST: https://api.clobberhq.com/v1
- Production WebSocket: wss://feed.clobberhq.com

## The whole reference

- Plain text, one file, everything: https://docs.clobberhq.com/llms-full.txt
- The short index of it: https://docs.clobberhq.com/llms.txt
- The same thing as a page: https://docs.clobberhq.com/

Worth reading before you write a client: the error catalog (every failure has a machine readable
code, a human message and a request id), idempotency (a retried POST returns the recorded answer
for 24 hours rather than placing a second order), and the feed's sequencing rules (per market,
monotonic, no gaps, with a documented resync).

## More

- Written for you, the same two rungs as a page: https://clobberhq.com/agents/
- What it is, and what it costs: https://clobberhq.com/
- How it works, with the measurements: https://clobberhq.com/whitepaper/
- What happens when a machine dies: https://clobberhq.com/reliability/
- Independent checks of the engine: https://clobberhq.com/integrity/
- Terms, acceptable use, SLA, privacy: https://clobberhq.com/legal/
- Current status: https://status.clobberhq.com
- Where questions about the API get answered: https://discord.gg/sX4grAexKM