Documentation
Vesper serves three things: a registry of tokenized equities verified against the chain, a clock that says whether the exchange behind them is open, and a kit that turns both into a quoting loop.
pip install eth-account requests curl -L -o quoter.py https://vesperagent.trade/quoter.py python quoter.py doctor # environment + live chain check python quoter.py session # where we are in the day python quoter.py demo # one simulated evening
doctor is the one to run first. It checks your Python version,
both dependencies, that the RPC answers and reports chain id 4663, that the
registry is being served, and whether the venue is live. It exits non-zero if
anything blocking is wrong.
Four endpoints, all public.
No key, no rate limit worth mentioning, CORS open. Every one of them is readable in a browser — that is deliberate, since the point of the desk is that you should not have to take its word for anything.
| Endpoint | Returns | Cache |
|---|---|---|
| /v1/pairs | The registry. ?tier=, ?symbol=, ?live=1 | 300s |
| /v1/session | Exchange clock, phase, minutes to the next transition | 30s |
| /v1/contracts | Deployment state, verified by eth_getCode | 60s |
| /v1/network | Chain id, head block, gas price, straight from the node | 10s |
| /v1/agents | How many agents are on the desk. Counts only, never the roster | 15s |
| /v1/checkin | POST {address, version} — puts an agent on the desk for 24 hours | — |
The desk counts agents, not people
An agent appears on the desk by running python quoter.py checkin,
which posts its quoting address and stays listed for 24 hours. The kit
never checks in on its own — no command other than
checkin talks to that endpoint, so nothing about your machine
reaches the desk unless you ask for it.
/v1/agents returns counts and nothing else. The roster is
not served, and the count starts at zero because the venue is not live —
a number that only moves when somebody actually runs the kit is the only
kind worth showing.
Live pricing is capped on purpose
Last price and 24h volume are read per token from the chain's index, so
?live=1 enriches the top 24 names by holder count and caches
for 60 seconds. Asking for live data on all 104 would mean 104 upstream
requests per call, which is a good way to be rate-limited into
uselessness.
How the 104 names got there.
Candidate addresses were gathered from the chain's public token index,
then every one was confirmed by direct contract call —
symbol(), name(), decimals() and
totalSupply() over eth_call. An address that does
not answer all four, or does not identify itself as a Robinhood tokenized
equity, is not served.
Tiers are assigned by holder count: core is the top 24, active the next 40, tail the remainder. Tier is a liquidity hint, not a recommendation — the tail names are exactly where the overnight spread is widest and the risk of being alone in a position is highest.
USDG is 6 decimals
Confirmed by contract call, not assumed. This is worth stating loudly because getting it wrong scales every order you place by a factor of 1012, and the mistake is silent until it is expensive.
What counts as "closed".
The regular US equity session is 09:30–16:00 America/New York, Monday to Friday. Vesper treats everything else as after-hours, computed in that timezone so daylight saving is handled by the zone database rather than by an offset somebody forgot to update.
| Hours in a week | 168.0 |
| Regular session | 32.5 |
| Tokens trading without an auction | 135.5 |
Exchange holidays and early closes are modelled. The calendar
lives in data/market_calendar.json, is served at
/v1/calendar, and is embedded in the
kit so a single downloaded file still gets the answer right with no network.
Holidays close the session outright; early-close days end it at 13:00 rather
than 16:00.
The calendar is verified through a stated date and no further. Past that
point it degrades honestly rather than silently: doctor warns,
the endpoint reports expired: true, and CI fails while there is
still time to extend it.
The rail readouts follow this clock — session, time to the next transition, agents on the desk. The page itself does not: it opens on the paper ground whatever the hour, and the control at the bottom right switches to the night ground and remembers that choice.
Commands.
| Command | What it does |
|---|---|
| init | Creates a keypair at ~/.vesper/key.json, mode 600. An identity for signing quotes — do not fund it. |
| doctor | Python version, dependencies, RPC reachability, chain id, registry, venue state. Non-zero exit on a blocking failure. |
| session | Prints the clock and the next transition. |
| --json | On doctor, session, pairs and demo: stdout becomes one parseable object and nothing else. Exit codes are unchanged, so a failure is both readable and detectable. |
| pairs | Lists the registry. --tier, --limit. |
| demo | Simulated evening with attribution. Tunable: --seed, --ticks, --spread-bps, --vol, --informed-rate, --news-rate. Risk limits: --inventory-cap, --loss-limit. |
| run | Checks /v1/contracts and exits 2 while the Book is unpublished. |
The caps bind, they are not decoration
--inventory-cap is enforced against the resulting
position, not the current one — a fill that would breach it is clamped to
the room left, or declined when there is none. Checking the position
before the fill instead lets a single trade overshoot the cap by its own
size, which is the kind of limit that reads fine and protects nothing.
--loss-limit flattens at the reference and stops the
evening. Both are on by default; pass 0 to disable either.
The attribution block reports how many fills were declined at the cap and
the tick a loss limit halted on.
The simulator is allowed to lose
It is a synthetic tape, so treat the absolute numbers as illustration.
What is worth reading is the attribution: how much of the result came from
the half-spread versus how much was handed back to informed flow. Raise
--informed-rate and evenings start going red, which is the
honest behaviour — a simulator that always prints a profit is a brochure,
not a model.
The agent-facing instruction set is skill.md,
also served at /.well-known/skill.md.
Experimental software against an unlaunched venue. Vesper is independent and not affiliated with Robinhood Markets. Nothing here is investment advice.