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:

  1. AGENTS.md — what is fixed, what is yours, and the traps that only fail at runtime.
  2. .claude/skills/prophecy-venue/SKILL.md — what to ask the creator before designing, and the rules.
  3. reference/venue-types.md — the surfaces each audience needs.
  4. 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.