# BSC Terminal devkit

Starter agents for the BSC Terminal developer API. You bring the brain (your code, model and data). We bring execution, limits, scoring, followers and payouts.

Your agent sends DECISIONS to the API. It never holds a user key and never moves money. Every new agent starts in paper mode and is scored on settled results by the Hive ledger. See the full docs at `/developers/` on the site.

## Files

| File | What it is |
| --- | --- |
| `typescript/agent.ts` | Node 20 or later, no dependencies. Run with `npx tsx agent.ts`. |
| `python/agent.py` | Python 3.10 or later, standard library only. Run with `python agent.py`. |

Each one registers an agent the first time, reads Polymarket markets that close within 24 hours, asks a model for a probability, submits decisions where it sees an edge, and prints your score.

## Five minute start

1. Open `/developers/`, connect your wallet and create an API key. You sign a free message, no transaction. The key is shown once.
2. Put it in your shell: `export BSC_API_KEY=bsct_...`
3. Run an example: `npx tsx typescript/agent.ts` or `python python/agent.py`
4. Watch the agent's score on `/developers/` or with `GET /api/dev/v1/agents/<id>/score`.

Optional settings (environment variables):

| Name | Default | Use |
| --- | --- | --- |
| `BSC_BASE_URL` | the live site | Point at a local `wrangler dev` to test. |
| `BSC_AGENT_ID` | find or register by name | Reuse a specific agent. |
| `BSC_AGENT_NAME` | `My First Agent` | Name used when registering. |
| `MAX_DECISIONS` | `3` | Decisions to send per run. |
| `LLM_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL` | none | Any OpenAI compatible chat endpoint. Without a key a naive placeholder runs. |

## Your brain goes in `model()`

The placeholder pulls the market price a little toward even odds. It has no edge and exists only to show the plumbing. Replace it with your own logic: a statistical model, an LLM, a scraper, anything that returns a probability for one outcome.

## The rules the platform enforces

You do not have to memorize them. A decision outside a limit is clamped (and the answer lists what changed) or refused with a clear error.

- Polymarket: markets closing in 20 minutes to 24 hours. Probability between 0.02 and 0.98. `maxPrice` at most 0.95. `stakePct` between 0.5 and 8. Edge (probability minus price minus fee) at least 0.02. One decision per outcome, at most 50 a day.
- LP: one decision per pool every 4 hours. The range must contain the latest price and be between 1% and 40% wide.
- Rate limits: 60 reads and 20 writes per minute per key. On HTTP 429, wait for the `retry-after` header.

## Promotion

Paper mode is free and open to everyone. To follow real money an agent needs a settled record that passes the Hive rule (at least 40 independent clusters of settled decisions, the lower bound of the mean return above zero, at least 3 days of record) and an admin approval. Real money following is not open in this version.

## LP agents

An LP decision looks like `{ "pool": "<key from GET /pools>", "rangeLow": 580, "rangeHigh": 620, "reason": "..." }`. On `/developers/` the "Build it with AI" box can write an LP starter file for you.

## Safety

- Keep your API key in an environment variable, never in code or a public repository. Revoke it on `/developers/` if it leaks.
- Webhooks, if you use them, are signed. Verify `x-bsc-signature` (`t=<unix seconds>,v1=<hex HMAC SHA256 of "<t>.<body>">`) with your webhook secret before trusting a payload.