Make a venue
One command scaffolds a branded prediction venue, your own AI designs it, and one command puts it live. Written for the agent doing the work as much as the person asking for it.
What you are building
A venue is a branded prediction market: a site where an audience takes positions on the things they already argue about. You do not build the trading — that arrives working. You build everything around it: the look, the language, the shape of the page.
Markets are global objects and a venue is a view over them, so a venue is defined as much by which markets it shows as by how it looks.
What you need
-
A Prophecy access key. Everything Prophecy publishes is restricted, and the key is what unlocks it — for scaffolding as much as installing. Configure it once, before anything else:
npm config set //registry.npmjs.org/:_authToken=<your key>Without it, npm answers 404 for
@prophecy-dev/*— that means not signed in, not “this package does not exist”.
Handing this to an agent? Give it launch-a-venue.txt instead — the same
path as commands, without the explanations. This page is the one to read if you want the why.
What to say in the message is on Prompt to venue.
1 · Scaffold
npm init @prophecy-dev/venue@latest book-club -- \
--name "Book Club" --about "novel" --terms "Winds of Winter,publisher,release date"
Say @latest, and do not pin. Without a tag at all, npx reuses whatever it has cached — which can
be a release old enough to predate the scope check below, and it scaffolds a venue and exits 0 while
doing it, so nothing tells you it happened. @latest forces npx to resolve against the registry,
which is the whole reason a version was ever written here.
A fixed version solved that and created a worse problem: this page said @0.2.0 for long enough
that the current release is 0.7.0, so every reader was handed a scaffolder five versions stale, by
a page telling them that was the careful thing to do. A pinned version in prose has no way to age.
Do not reach for @^0.7.0 to mean “0.7 or newer” either — below 1.0 a caret is bounded by the
minor, so ^0.7.0 refuses 0.8.0 and you have quietly pinned again. The scaffolder is a one-shot
that writes code you then own, so newest is always what you want.
--about is the venue’s standing query and --terms widen it. Together they decide what appears on
the board.
Scope by names that appear in market TITLES, not by the topic. This is the single thing most worth getting right, and the instinct — describe the subject, then make the description more precise — is the wrong axis. Measured on testnet:
| query | markets |
|---|---|
"book releases" |
0 |
"books" |
1 |
"novel" |
3 |
"Winds of Winter" |
2 |
"Formula 1" |
0 |
"Verstappen" |
1 |
Being more specific made it worse, because specificity is not what the index matches on. A market
is titled “The Winds of Winter publication by 31 Dec 2026”, so it is found by Winds of Winter,
publication and novel — and not by any phrase describing the category it belongs to. Pick the
nouns your markets’ titles actually contain: books, drivers, tickers, clubs, candidates.
Three terms are used; more are accepted and ignored.
Two flags worth knowing: --sovereign builds a venue that never calls us at runtime, and
--skip-scope-check turns off the check below. Skipping it is almost always a mistake — it is the
only thing between you and an evening spent designing an empty board.
The scaffold then tells you whether it worked, before you install anything:
Scope check — testnet (testnet.api.prophecyhosting.com)
about "novel" 3 on the board
term "Winds of Winter" 2 on the board
ON THE BOARD: 4 markets.
ON THE BOARD: 0 means visitors will see an empty venue however good the design is. Fix the terms
and run the command again — it costs ten seconds now and an evening after the venue is designed.
A thin board is not the end of the subject — you can create markets on any of it. Two commands,
self-serve, no operator: prophecy markets "<topic>" sources a verified slate and
prophecy markets mint --topic "<topic>" <id>… mints the ones you pick. Prophecy covers the oracle
fee, the gas and the seed, so it costs you nothing; the caps are 8 per call and 20 per venue per
day. Step 5 below walks through it.
A venue can also mint from inside its own UI, from a template, and that route is narrower today:
crypto.updown and crypto.threshold work, while stocks.close and the four football kinds are in
the contract and answer template-unavailable (501). Both routes, and what each costs, are on
Creating markets.
2 · Design
cd book-club
npm install # the venue's own dependencies
npm run dev # http://localhost:3000
You should see a working venue with real markets before you change anything. If the board is empty, the scope check above already told you so — fix that first, because no amount of design fixes an empty board.
Point your AI at the folder and describe the venue you want. You do not need to explain the
rules — the scaffold ships AGENTS.md and a skill in .claude/skills/, so the agent already
knows the components, the house style, and the one rule that matters:
Restyle and restructure freely. Never rewire. The predict/sell path lives inside the kit and in the checkout drawer mounted once in
app/providers.tsx. A page can look like anything and still cannot break trading, because it never touches it.
Before you design, settle who the venue is for — it changes the shape more than any styling choice:
| wants | build | |
|---|---|---|
| trader | the edge | charts, live flow, positions, density |
| player | the game | fast, mobile, one decision per screen |
| debater | to be proved right | comments, follows, resolution receipts |
The kit ships comments, takes and a community feed. If your audience argues about the subject, put that on the page — a venue is a place people talk, not only a board.
What a design pass costs, so you can budget the session: roughly 3k tokens in and 1.6k out per pass, so a ten-pass session is around 46k. Iterating is cheap; it is meant to be.
If you are pasting your access key into a hosted agent, remember that key then lives in that conversation’s transcript and in its sandbox. Fine for a key you already hold and can rotate; think before it becomes the routine way keys get handed out.
3 · Check
The guard and the deploy path live in one tool. Install it once:
npm install -g @prophecy-dev/studio@latest # or: npx --package @prophecy-dev/studio prophecy …
prophecy validate
Refuses a venue that renders no market surface, hand-rolls a quote, unmounts the checkout, quietly reads the global market pool, or sets ink colours it cannot know are legible. It runs again at deploy, so a venue that fails here cannot ship. Fix the cause it names rather than working around it.
It re-runs the scope check too, against the venue as your agent has left it — an agent that edits
app/venue-markets.ts can narrow the board without noticing. The guard decides the exit code; the
scope check only reports.
…and look at it
npm run shot # renders the venue, writes shots/desktop.png and shots/mobile.png
Everything above reads source. This is the only check that sees the page, and it is the one an
agent cannot perform for itself. Three defects survived a green validate on the first outside
build — lone half-width cards in a two-column grid, a browser-default 168px textarea, and a composer
crushed into a 320px rail — all obvious within two seconds of looking, and invisible to every rule.
It also reports what the rendered page admits to: cards on screen, console errors, a hero that buries
the markets, horizontal overflow.
It needs Playwright, which is not bundled because it is a browser — and Playwright has to be
resolvable from the CLI, not from the venue. --shot imports it from wherever the CLI lives, so
installing it inside the venue does nothing for a globally installed prophecy. One of:
npm i -g playwright && npx playwright install chromium # matching a global CLI
npx --package @prophecy-dev/studio --package playwright prophecy validate --shot # or via npx
npm i -D playwright # or at the ROOT that resolves the CLI
Open the PNGs. If you are an agent and cannot see images, say so rather than calling the venue done.
4 · Create the venue
The venue needs a key of its own. Issuing that first key is creating the venue — there is no separate step:
prophecy login # creating, minting and deploying all need a sign-in
prophecy venue create "Book Club" # prints the venue id and its key, once
Note the venue id it prints. It is slugged from the name (book-club), and it is not necessarily
your directory’s name — every command below takes it explicitly.
Ownership is per network. venue create registers the venue on testnet unless you pass
--network mainnet, and a venue registered on one network does not exist on the other. The key that
goes in the bundle must come from the network the venue’s build reads (const NETWORK in
app/providers.tsx).
Prophecy hosting checks ownership on mainnet today, whatever network the build is on — so a venue
registered only on testnet is refused at prophecy deploy with “Prophecy has no venue … for you”.
Until that changes, a testnet venue you want hosted is registered on both:
prophecy venue create "Book Club" # testnet — its key goes in the bundle
prophecy venue create "Book Club" --network mainnet # what hosting's ownership check reads
Signing in without a browser
On a headless box — an agent, a container, CI — prophecy login still works. It is two commands
rather than one:
prophecy login --headless # prints a URL and exits; it does not wait for anything
prophecy login --code 123456 # the six digits the sign-in page showed
Open that URL on any device you do have a browser on, sign in, and read the six digits back. They
last 10 minutes. The CLI already assumes headless over SSH, in Codespaces, Gitpod and Cloud Shell,
and on Linux with no DISPLAY; PROPHECY_HEADLESS=1 forces it anywhere else, and
PROPHECY_HEADLESS=0 forces the browser path back on.
A sign-in lasts about an hour. For repeat deploys there is a token that does not expire, covered in step 6 — don’t export it into your shell, for the reasons given there.
PROPHECY_ACCESS_TOKEN is also honoured, and it is not the same thing: it is a short-lived
sign-in token, so it lapses with the session it came from. Reach for it only if you already hold
one.
5 · Give it markets of its own
Any topic, self-serve, no operator, and it costs you nothing. The venue has to exist first — minting checks that you own it, on the network you mint to. Source a slate, then mint from it by id:
prophecy markets "premier league"
prophecy markets "tfl disruption" --angle "line suspensions" --count 20
prophecy markets mint --topic "premier league" --venue book-club <id> <id>
The ids come from the first command and only from it — --topic is how they are found again, so it
has to match the topic you sourced under. Sourcing takes a couple of minutes: it generates
candidates and then runs each one through the gate that decides whether a market can actually
resolve. Every id you then pick is re-checked independently at mint time and refused if it fails, so
a slate entry is a candidate, not a promise.
Pass --venue. Without it, mint targets the directory name, which is not the venue id whenever
the two differ — and minting for a venue you don’t own on that network is refused
(no-venue-on-network).
Up to 8 per call, 20 per venue per day. It mints to testnet unless you pass --network mainnet,
and the venue must be registered on the network you pass.
A minted market appears on your board only if the venue’s scope matches its title. Run
prophecy validate afterwards and check the scope count went up; widen the terms in
app/venue-markets.ts if it did not.
Creating markets has the other routes and what each one costs.
6 · Go live
prophecy deploy --key pck_… --venue book-club
Pass --venue whenever you pass --key. It is what stops the bundle claiming one identity while
carrying another’s key, and venue create prints both. PROPHECY_VENUE_KEY and PROPHECY_VENUE_ID
are read for the same two values, so a CI job need pass neither.
For repeat deploys from an agent or CI, use a token that does not expire. Issue it after the venue exists, on mainnet — hosting checks ownership there, and a token issued on testnet (the default) isn’t recognised — and hand it to the one command that needs it:
prophecy token create --venue book-club --network mainnet
PROPHECY_DEPLOY_TOKEN=pdt_… prophecy deploy --key pck_… --venue book-club
Shown once. It is bound to that one venue, proves ownership and nothing else, is revocable on its
own, and must never go inside the venue’s bundle. It authorises deploy and secret, and nothing
else: venue create, venues and token create need your sign-in, and a mainnet-issued token can’t
mint on testnet. Don’t export it. When it is set, the CLI uses it in preference to your sign-in
for every command, so those commands would start refusing you.
Signed in, deploy puts the venue on Prophecy’s own infrastructure — you never touch a
Cloudflare account and you need no credentials of ours. The built venue is uploaded to Prophecy,
which checks you own the venue and publishes it.
So if you find yourself looking for a CLOUDFLARE_API_TOKEN, stop — the fix is to sign in, not to
find a Cloudflare key. Setting one is worse than not having it: it switches deploy to the
operator path, which uploads directly and never registers the venue in the studio gallery.
Size. Prophecy hosting takes a built venue up to 60 MB, and no single file over 25 MB
(Cloudflare’s own limit). A typical venue is around 12 MB, so this is far more room than a venue
with pictures needs. deploy checks before it uploads and names the largest files if you are over.
If your venue genuinely needs more, talk to us — or self-host.
Without a sign-in it falls back to deploying into your own Cloudflare account. That works, but
sign-in is allow-listed by domain: *.venues.prophecyhosting.com is covered, a workers.dev
hostname is not, so the board renders and login fails until Prophecy allow-lists it. The CLI says so
at the moment it happens.
Both come from @prophecy-dev/studio, installed above.
Live at https://book-club.venues.prophecyhosting.com. Deploying again is the same command; that is
how you iterate.
7 · Testnet, then mainnet
Everything above is testnet by default — the scaffold, the venue registration and the mint all are. Going live is three separate switches, and nothing makes them agree for you:
npm init @prophecy-dev/venue@latest book-club -- --network mainnet # scaffold on mainnet
prophecy venue create "Book Club" --network mainnet # register on mainnet
prophecy markets mint --topic "premier league" --venue book-club <id> --network mainnet
The deployed build’s network comes from the venue’s own source, not from prophecy.json. The
deploy reads const NETWORK in app/providers.tsx; the network field in prophecy.json is not
read by anything. So a venue whose config says mainnet and whose providers.tsx still says
testnet ships a testnet build to a mainnet hostname — it renders perfectly, signs people in on
one network and reads the other, and nothing on the page admits it. That has burned a real venue.
To move a venue that already exists, edit const NETWORK (and the API host beside it) in
app/providers.tsx, then redeploy. Check it either side of the change:
prophecy venue show # venue id, worker name, network, hosted URL, scope — no sign-in needed
venue show reads the network out of the source, and says so out loud when prophecy.json
disagrees with it. Believe that line, not the file.
The rest of the CLI
Beyond validate, deploy and markets, the commands you are most likely to want:
prophecy venues |
The venues you own. |
prophecy venue show [dir] |
What this venue is and where it deploys. Needs no sign-in. |
prophecy token create --venue <id> --network mainnet |
A deploy token that does not expire. For deploy and secret only — pass it inline, don’t export it. |
prophecy secret set <NAME> |
A server-side secret. The value is read from stdin, never a flag: printf %s "$KEY" | prophecy secret set STRIPE_KEY. |
prophecy secret list / rm <NAME> |
The names on this venue — values cannot be read back — and removal. |
prophecy request <what> |
Ask the Prophecy team for something you need. |
prophecy request --status <ID> |
What happened to a request you filed. |
A secret is readable only from server code — a route handler, a server component, a server
action — through import { env } from "cloudflare:workers". It is not in the browser bundle and must
never be passed into a "use client" component. It applies to the deployment that is live now, with
no redeploy.
prophecy request is the thing to reach for instead of guessing or giving up. It tells you whether
others have asked for the same thing, which is what gets it built.
When it goes wrong
Every row here has actually happened, most of them more than once.
| symptom | cause |
|---|---|
404 on @prophecy-dev/* |
The access key is not configured. Restricted packages answer 404, not 401, so this reads like “no such package”. Check npm whoami first. |
Looking for a CLOUDFLARE_API_TOKEN |
You are not signed in. Run prophecy login (or --headless), or pass a deploy token to deploy; do not go looking for a Cloudflare key, and do not set one. |
| Venue renders but the board is empty | The query, not the design. Check app/venue-markets.ts and re-read the scope check. |
| The page looks fine and the text is invisible | Hard-coded ink. Use var(--pc-*); validate catches this now. |
<MarketGrid> shows unrelated markets |
It was rendered without an events prop, so it fetched the global pool. Pass the venue’s own useVenueMarkets() from app/venue-markets.ts. |
npm run dev dies on pino |
An old scaffold. Current ones pre-bundle it in vite.config.ts. Re-scaffold with @latest. |
| Cloudflare 500 on asset upload | Deploying the venue’s root wrangler.jsonc. Deploy dist/server/wrangler.json — prophecy deploy does. |
prophecy --version prints usage and exits 1 |
There is no version flag. Not a broken install. |
| The browser shows an old error after deploying | Chrome caches the error page. Add ?x=1. |
For the agent reading this
The venue you scaffold contains its own instructions. After step 1, read in this order and stop when you have what you need — each is loaded only when it is relevant:
AGENTS.md— what is fixed, what is yours, and the traps that only fail at runtime..claude/skills/prophecy-venue/SKILL.md— what to ask the creator before designing, and the rules.reference/venue-types.md— the surfaces each audience needs.reference/kit.md— every component and hook with its verified signature. If a prop is not listed there, do not pass it: a venue is not typechecked at build time, so a guessed prop compiles, deploys, and throws on a visitor’s screen.
Two things worth knowing before you write anything. Get markets from useVenueMarkets() — which is
not a kit hook: it is generated into the venue at app/venue-markets.ts, and it is where the
scope lives, so import it from there rather than writing your own. Never a bare <MarketGrid />:
the bare one fetches the global pool, which is how a venue about books fills with football. And
colour from var(--pc-*) rather than hard-coded values: the shell paints the
page, so a literal colour is a guess about someone else’s background, and that is how a headline ends
up invisible on a page that is otherwise perfect.