# Velven

> The community marketplace for spaces built with AI. Games, worlds, tools, wonders. Spaces stay where they are hosted; Velven is where they get found, entered and ranked.

## Documentation

- [All docs](https://velven.ai/docs): the quickstart, the SDK guide, listing with an agent, hosting and proof, the skills, the REST API and the crawler; every guide is also served as markdown.
- [Quickstart (markdown)](https://velven.ai/docs/quickstart.md): listing a space by hand on the add page.
- [REST API (markdown)](https://velven.ai/docs/api.md): every endpoint, with boards, secrets and bans in full.
- [VelvenBot (markdown)](https://velven.ai/docs/bot.md): what the crawler fetches and how to keep it away.

## For coding agents

- [List a space with an agent (markdown)](https://velven.ai/docs/agent.md): device-code login, then one POST to list a space. Exact curl examples, response shapes, error codes, allowed values.
- [List a space with an agent (HTML)](https://velven.ai/docs/agent)
- [SDK guide (markdown)](https://velven.ai/docs/sdk.md): sign-in, hosted leaderboards and saves inside the frame, as one file. The script tag, the npm package `@velven/sdk`, the boards block, the server tier, the local environment.
- [SDK guide (HTML)](https://velven.ai/docs/sdk)
- [Hosting and proof (markdown)](https://velven.ai/docs/hosting.md): the six hosts, where the proof tag goes on each, the framing header per host, and what Velven checks when.
- [Agent skills (markdown)](https://velven.ai/docs/skills.md): Velven's skills in the skills.sh format, `npx skills add velvenai/skills`; the `onboard` skill lists a space or claims one and adds the leaderboard. Source at https://github.com/velvenai/skills.

## API

- POST https://velven.ai/api/agent/login: start a login, returns a verification_url and a device_code.
- POST https://velven.ai/api/agent/token: poll with the device_code until the creator approves.
- GET https://velven.ai/api/agent/me: which creator a token belongs to.
- POST https://velven.ai/api/spaces: list a space (bearer token). Hosts: Vercel, Netlify, GitHub Pages, Cloudflare, Replit, ChatGPT sites.
- POST https://velven.ai/api/spaces/verify: prove the creator built it (meta tag).
- GET https://velven.ai/api/spaces?mine=1: the creator's listed spaces.
- GET and PUT https://velven.ai/api/spaces/{slug}/boards: a space's leaderboards (bearer token); POST https://velven.ai/api/spaces/{slug}/secret issues the server tier's secret; DELETE .../scores/{id}, POST and DELETE .../bans moderate.
- POST https://velven.ai/api/v1/scores: a space's own server posts a score with x-velven-secret, the player's identity token and a request_id. GET reads a board's rows. Details in the SDK guide.
- GET https://velven.ai/.well-known/jwks.json: the public keys the identity tokens are verified against.

## In the browser

Pages expose their actions as WebMCP tools on document.modelContext (Chrome origin trial): search_spaces on every page; inspect_space_url and publish_space on /add; check_claim on a claim page; enter_space, upvote_space, save_space and report_space on a space page; email_sign_in_link and choose_handle on sign-in. Details in the agent guide.