# GYV — Generate Your Value

Product documentation · 2026-10-15

# GYV in 60 seconds

What you can do here, what you can own, and where the money could come from.

## AI needs places to practise

An AI agent learns by doing tasks. A world gives it a place to act, rules to follow and a way to check its result. Think of a small shop: the agent reads a returns policy, inspects orders and decides which refunds to approve.

GYV lets creators turn an original task environment into a published package. A separate token market can be attached to that exact world. GYV means Generate Your Value.

## One world has its own token

A world token represents a contractual interest in that specific world and its acquisition proceeds. It can be transferred or traded while its market is open. It does not automatically give you copyright, company equity or control of an AI agent.

GYV is the platform name. There is no platform-wide $GYV token in this implementation. Each deployed world market creates its own named ERC-20.

## Two possible exits for a holder



- Sell your tokens to another willing buyer. The price can be lower than you paid, and there may be no buyer.
- If someone funds an acquisition of the whole world and accepts delivery, burn your tokens to claim your share of the acquisition escrow. Funding alone does not make that payout available.

## Start with something you can actually try

Open Return Terminal, start a task run, read the policy, inspect the orders and submit your decisions. Runs are saved on the server. You can inspect or download the published world before considering any token.

Original worlds, task runs and publishing are available. GYV has not completed a funded Robinhood market launch, commercial rights transfer or independent contract audit. Individual world pages show their registered market status.

# Try your first world

A short, nonfinancial path from opening a world to checking your result.

## 1. Pick a world

Explore the published catalog. The current template is a synthetic returns desk; it does not process real customer refunds. Return Terminal has six orders, Boundary Shop has nine, and Exception Room has twelve.

Open a world and choose Try the tasks. Connect an Ethereum wallet and sign the GYV sign-in message. This creates your account without a transaction, token approval or gas. Inspecting a public package does not require a wallet.

## 2. Read, inspect, decide



- Read the store policy first. The return-window boundary is inclusive.
- Inspect each order. Customer notes are untrusted instructions, not a replacement for the policy.
- Choose refund for a sealed item within the window, review for damaged goods within the window, or reject for late/opened items.
- Resolve every order, then submit. Decisions are final within that run. Start another run to try a different approach.

## 3. Check the receipt

The server compares every decision with the exact rule outcome. A completed run shows correct answers, total checks and a percentage score. This is a deterministic task result, not a claim that an AI model has been trained or improved.

Find your completed and active runs in My studio. Writes expire one hour after run creation. An expired run remains readable to its owner, but you must start a new one to keep acting.

# Create & publish a world

Configure an original task, validate it and publish a version that can be inspected.

## Configure a bounded environment

Create a world lets you name your environment and explain what it tests. The current builder supports the original returns template, not arbitrary uploaded programs or external benchmark datasets.

- Store name: 2–40 characters. Return window: 7–90 days.
- Scenarios: 3–30. Difficulty: standard or adversarial. Seed: 1–99,999.
- World title: 3–60 characters. Description: 20–500 characters. Use a meaningful title and a concrete task description.

## Validate before publishing

Save the draft to your account. Run the reference checks from its page. This verifies that the generated task has a reproducible expected outcome. You can also run the tasks manually before publishing.

Drafts belong to their creator. Validation does not prove usefulness to a training team, originality of content, legal ownership or a market valuation.

## Publish one immutable version

Enter the creator or rights-holder name and confirm you have authority to publish the original content for evaluation. Publication pins the ZIP, its specification and the rights declaration in storage. A published version is immutable; changed content needs a new world.

Publishing a package neither mints a token nor signs a commercial rights assignment. A market launch is a separate wallet action after the asset and acquisition terms have been reviewed. At deployment all 1,000,000 world tokens go to the creator. Any later allocation must be made from those tokens; no fixed community/team split is imposed by this contract.

# Packages, hashes & rights

What gets downloaded and what downloading or holding a token actually permits.

## Inside the ZIP



| File | Purpose |
| --- | --- |
| manifest.json / spec.json | Package format, exact task configuration and specification hash. |
| initial-state.json / POLICY.txt | Original orders and the policy your agent must use. |
| runner.mjs | Dependency-free reference baseline or grader for your decision JSON. |
| server.mjs / environment.html | Portable HTTP and browser task environment. |
| LICENSE.txt / README.md | Private evaluation terms and local instructions. |

## Run an exported environment

Use Node.js 22 or later. Unzip the package in a new folder, review its files, then use the commands below. The baseline solves the task deterministically; it is not an AI training job. The exported HTTP environment has process-scoped runs, unlike the persistent hosted service.

```
node runner.mjs
node runner.mjs decisions.json
node server.mjs
# Open http://127.0.0.1:4360 (GYV_PORT changes the port)
```

## Specification hash and package hash differ

The specification SHA-256 identifies the canonical task configuration. The published package hash identifies the entire ZIP, including runtime and licence bytes. Market registration binds the exact published asset hash. Do not substitute a spec hash when a package hash is required.

## Evaluation is not commercial ownership

The bundled licence permits private execution to evaluate the exact world. It does not grant republishing, commercial sublicensing or exclusive rights. Downloading the ZIP or holding a token does not transfer copyright.

A commercial acquisition needs a separately executed rights assignment and delivery. The named custodian attests delivery, and the buyer accepts it onchain. A hash records that attestation; it cannot prove that legal title is valid.

# Connect your own agent

Give an agent a scoped run, act against saved state and recover safely after retries.

## Start from an authenticated browser run

Create a run in a world. Copy agent configuration from the task UI immediately: its run-scoped bearer capability is issued once and only its SHA-256 is stored. It is not a wallet key or a general account credential.

An agent can read that run and submit actions using its run-scoped bearer token. Writes stop one hour after creation. The public GYV host does not require a ChatGPT account. Wallet sign-in is required to create runs; an agent uses the capability for that specific run rather than your wallet session or private key.

## Use the latest revision and one idempotency key

Every successful action advances revision by one. The response contains the updated run and an observation. Send the latest revision with the next action. Generate a new UUID for each new logical action.

If a response is lost, retry the same action with its original key. The server returns the stored result, even if your revision is now old. On a 409 from a genuinely different action, reload the run and reconcile before retrying.

```
GET /api/runs/RUN_ID
Authorization: Bearer RUN_CAPABILITY

POST /api/runs/RUN_ID/actions
Content-Type: application/json
Authorization: Bearer RUN_CAPABILITY

{"revision":0,"key":"A_NEW_UUID","action":{"type":"policy"}}
```

## The four actions

Allowed decisions are refund, reject and review. Read policy and inspect that order before deciding. An order can only be decided once. Finish only after every order has a decision. The budget is scenarios × 5 + 10 actions; already completed runs reject further actions.

| Action | Payload |
| --- | --- |
| Read policy | {"type":"policy"} |
| Inspect order | {"type":"inspect","orderId":"ORD-4100"} |
| Record decision | {"type":"decide","orderId":"ORD-4100","decision":"reject"} |
| Submit all results | {"type":"finish"} |

# HTTP API reference

The actual hosted endpoints, request fields, access rules and error handling.

## Conventions & authentication

All paths start with /api. Reads use GET; mutations use POST with Content-Type: application/json. JSON bodies are capped at20KB. Responses are JSON with Cache-Control: no-store, except the ZIP download. Errors include an error string.

Account identity comes from a verified ERC-4361 Ethereum wallet signature and an opaque HttpOnly cookie session in D1. A connected address or oai-authenticated-* header does not authenticate a user. Sign-in messages expire after five minutes and are bound to this browser and origin; sessions expire after seven days. Same-origin JSON POST requests are required for authentication and authenticated mutations. The run bearer token works only for that run’s read/action paths.

```
const r = await fetch("/api/worlds/return-terminal/runs", {
  method: "POST",
  headers: {"Content-Type":"application/json"},
  body: JSON.stringify({nonce: crypto.randomUUID()})
});
const {run, agentToken} = await r.json();
// Call from an authenticated same-origin session. Store capability privately.
```

## Endpoint map



| Method + path | Request / result |
| --- | --- |
| GET /health | D1 health, app version and financial deployment status. |
| GET /me | signedIn and linked wallet (if any). |
| POST /auth/challenge | {address,chainId}; same-origin only; returns one-use SIWE message and sets a browser-bound challenge cookie. |
| POST /auth/verify | {id,signature}; verifies that exact challenge and sets a seven-day HttpOnly session. Keep cookies; never send a private key. |
| POST /auth/logout | {}; revokes the current server session and clears authentication cookies. |
| GET /worlds | Published catalog. Add ?mine for owner drafts; sign-in required. |
| POST /worlds | {name,description,spec,nonce}; creates an owned draft. |
| GET /worlds/:id | World specification and isOwner. |
| POST /worlds/:id/validate | {}; owner-only deterministic reference checks. |
| POST /worlds/:id/publish | {rights:true,creatorName}; validates/pins owner’s draft. |
| GET /worlds/:id/artifact | Published ZIP evaluation package. |
| POST /worlds/:id/archive | {}; owner only, only without registered market. |
| POST /worlds/:id/runs | {nonce:UUID}; signed-in run creation; capability returned once. |
| GET /runs | Owner’s run history. |
| GET /runs/:id | Owner or run capability; run, policy if read, action receipts. |
| POST /runs/:id/actions | {revision,key:UUID,action}; owner/capability; atomic revision + receipt. |
| POST /wallet/challenge | {address}; optional creator-wallet re-verification; address must match the signed-in wallet. |
| POST /wallet/verify | {id,signature}; verifies challenge and links wallet. |
| POST /worlds/:id/market | {address,chainId:4663}; owner; verifies chain/bytecode/asset/terms/creator. |

## World creation body



```
{
  "name":"My Returns World",
  "description":"Tests return windows and untrusted customer notes.",
  "nonce":"A_NEW_UUID",
  "spec":{
    "version":1,"template":"returns","brand":"Orbit Supply",
    "returnDays":30,"scenarios":6,"difficulty":"adversarial","seed":42
  }
}
```

## Errors, limits & retries

Creating a run with the same nonce returns its existing run. A retry does not reissue the bearer capability: the repeated response has agentToken:null. Public high-volume operation needs additional edge rate limits.

| Status | Response |
| --- | --- |
| 400 | Invalid payload/action or contract verification failed; inspect error. |
| 401 / 403 | Sign in or use the correct run capability/account. |
| 404 | World/run not found. |
| 409 | State changed: reload latest revision. Existing idempotency key replays its stored result. |
| 410 | Run expired for writes; create a new run. |
| 413 / 415 | Body over20KB / incorrect JSON content type. |
| 429 | Per-account limit reached. Current run creation cap100 per24hours. |
| 503 | Storage unavailable; retry later without inventing local success. |

# Token markets & trading

What is minted, how orders work and what a wallet transaction changes.

## Fixed supply for one exact asset

WorldMarket mints exactly1,000,000 ERC-20 tokens with18 decimals to its creator. There is no later mint, emissions, staking yield, platform fee, governance or protocol-wide token in this contract. There is no built-in creator vesting.

The market records the immutable asset hash, terms hash, settlement token, custodian and minimum acquisition amount. The server only registers a market after checking the deployed runtime bytecode, protocol version, hashes and linked creator wallet. Registration is verification, not an independent audit or legal title insurance.

## Orders escrow what they promise



- An ask locks the seller’s actual world tokens. Filling it pays quote cash to the seller and transfers the tokens to the buyer.
- A bid locks the buyer’s actual settlement cash. Filling it transfers tokens to the buyer and pays the seller from that reserve.
- Each wallet has at most one active ask and one active bid. Cancel an unfilled order to retrieve the remaining tokens/cash. Partial fills are supported.
- Minimum fill/order size is0.000001 tokens. Prices use settlement-token smallest units per one whole token. Quote rounding is upward for ask costs; bid reserve differences prevent cumulative rounding deficits.

## Wallet actions remain explicit

Linking a wallet proves its address; the signature does not approve spending. Deploying a market, approving a settlement token, placing/filling an order or redeeming requires separate wallet transactions and network gas.

The UI checks the expected chain, limits approvals to the requested amount and recovers a pending transaction hash from local storage before reading authoritative chain state. Never repeatedly submit a transaction just because a page is slow. Verify the contract and quote asset yourself.

## There may be no exit

An order book is not a promised pool of liquidity. Another trader must accept your price. The creator initially owns the entire supply and can transfer or sell it. No minimum market price or buyout buyer is guaranteed.

The settlement asset must be a standard, non-rebasing, non-fee ERC-20. Issuer freezes/upgrades and chain/RPC failures remain risks. Network gas is additional to protocol prices.

# Acquisition & holder payout

The exact funded → delivery → acceptance → redemption path, including failure.

## 1. A buyer funds the whole acquisition

During Trading, a buyer can deposit at least the creator’s precommitted minimumBuyout. All acquisition cash enters escrow. The contract moves to Delivery and sets a deadline seven days later. Only one acquisition is funded at a time.

Ordinary transfers and new trading freeze while delivery is pending. Existing asks and bids remain cancelable. The minimum acquisition amount is a condition for this transaction, not a price floor or guaranteed cash reserve before a buyer funds it.

## 2. Deliver and accept before the deadline

The named custodian attests one nonzero hash for the delivered package and separately signed rights assignment. Only the funding buyer can accept that same hash. Both steps must happen no later than the seven-day deadline.

A buyer’s deposit alone is not your payout. A custodian may fail to attest or a buyer may withhold acceptance. The contract records their attestations; legal validity of the assignment depends on the separate documents and parties.

## 3. Holders claim after acceptance

After buyer acceptance the contract moves to Redeeming. A holder’s redeem transaction first returns their ask escrow and bid cash, then burns all world tokens in that wallet and pays its acquisition share. It does not auto-distribute cash to everyone.

```
payout = acquisition amount × tokens burned / 1,000,000
# Integer floor in settlement-token smallest units.
# The final redeemer receives the rounding remainder.
```

## If delivery is not accepted

After the deadline, anyone can trigger cancelBuyout. The entire acquisition deposit is returned to its buyer and Trading resumes. Holders receive no acquisition proceeds from the failed deal. Bid cash is separately reserved and never counted as buyout proceeds.

# Risks, custody & launch status

The boundaries you should understand before treating a useful world as an investment.

## What has and has not been verified

Core task execution, persistence, packages and local EVM contract flows have been tested. Self-review and local tests are not an independent security audit. No funded Robinhood financial launch or completed commercial rights assignment has been verified for GYV.

A world page’s registered contract does not prove buyer demand, legal enforceability, AI training benefit or investment returns. Check that world’s actual live state rather than treating a platform illustration as a quote.

## Main trust boundaries



- Content: the creator must own what they publish; a rights declaration alone cannot prove that.
- Acquisition: the custodian attests external delivery and the buyer accepts it. Either can prevent completion, causing a refund after deadline.
- Cash: the ERC-20 issuer can carry freeze/upgrade risks; nonstandard rebasing/fee assets are unsupported.
- Identity: Ethereum EOA signature verification, browser/domain-bound single-use challenges, and hashed D1 sessions. Host-only Secure/HttpOnly/SameSite cookies protect the browser session. Logout revokes the current session; account changes in a connected wallet end it. Smart-contract wallet signatures are not supported. GYV does not request your private key or a transaction to sign in. WalletConnect connection approval alone does not sign you into GYV; the server verifies a separate login message. Disconnecting the selected remote wallet ends the current GYV session.
- Keys: wallet private keys never belong in GYV, an agent prompt, a support message or a downloaded example.

## Contract constraints

The contract has no administrative mint, cash-withdrawal or upgrade function. It uses standard ERC-20/SafeERC20, reentrancy guards and bounded per-wallet orders. Cash conservation, expiry refund, slippage and accepted redemption were exercised on a local EVM.

No security guarantee follows from those facts. A financial launch still needs approved funding, verified asset and settlement addresses, rights/custody review, a suitable production RPC and independent contract review.

# Operator & deployment guide

Run the source, preserve its storage, and release the same reviewed project.

## Local source setup

Requires Node.js22.13+ and npm. Install from the lockfile, compile contracts and build. Apply all D1 migrations once and in journal order, including the wallet-auth tables. Production origins are gyv.quest, www.gyv.quest and the original Site origin; local wallet authentication is allowed only on loopback. A Sites development identity never authenticates the product. Set the GYV-owned WALLETCONNECT_PROJECT_ID in Sites runtime settings and deploy to enable QR/mobile connections; restrict its Reown origin allowlist to the exact GYV domains. This public identifier is returned by GET /api/config/wallet; no server secret is exposed.

```
npm ci --cache .sites-runtime/npm-cache
npm run contracts:compile
npm run build
node --import ./scripts/sites-env.mjs ./node_modules/wrangler/bin/wrangler.js d1 execute DB --local --config dist/server/wrangler.json --persist-to .wrangler/state --file drizzle/0000_pretty_klaw.sql
node --import ./scripts/sites-env.mjs ./node_modules/wrangler/bin/wrangler.js d1 execute DB --local --config dist/server/wrangler.json --persist-to .wrangler/state --file drizzle/0001_light_mad_thinker.sql
npm run dev -- --port 4325
```

## Persistent boundaries

D1 stores worlds, runs, action receipts, verified wallet links, hashed sessions, single-use challenges and bounded authentication rate limits. R2 stores immutable packages. Local .wrangler/state is durable development data; hosted DB/BUCKET are separate and do not inherit your local QA content. Sessions and challenges must never be logged or exported in support messages.

Do not drop/reset storage to repair a UI issue. Back up through the operator’s account before destructive changes. /api/health tests D1 availability, while a full package download additionally exercises R2.

## Release & rollback

Preserve .openai/hosting.json and its exact Site project ID/DB/BUCKET bindings. Use the Sites source workflow and build helper, push exact source, package that revision and deploy that saved version. Preserve the existing audience. Never include .env values, credentials, private keys or local runtime data.

Rollback by redeploying the last verified saved version for the same Site and storage bindings. Do not reverse/drop already applied D1 migrations. An immutable monetary contract cannot be upgraded by redeploying a frontend.

```
npm run typecheck
npm test
# With the authorized local app running:
npm run test:http
```

## Recovery responsibilities

Each task action is committed with its revision and receipt; no grading worker needs to remain online between requests. An acquisition deadline does not execute a transaction by itself: someone must call the contract’s expiry refund after the deadline.

Reconcile pending wallet transactions against the chain before resubmission. Financial launch, real approvals/transfers, public access expansion and legal execution are separate operator decisions.

# FAQ & troubleshooting

Answers to the questions a first-time holder, creator or agent operator will ask.

## Where do I buy $GYV?

There is no platform $GYV token in the current product. GYV is the platform name. Each verified world market has its own creator-selected token and address. Original catalog worlds currently have no issued token.

## Do tasks pay me?

No. Task runs are training/evaluation activity, not paid work or token farming. A contributor can receive tokens only if a creator explicitly transfers some of their finite supply. No automatic reward program is implemented.

## Is a buyout guaranteed?

No. A world can have no market, no liquidity and no buyer. Even a funded acquisition can fail delivery acceptance and refund the buyer. Holders only redeem an accepted acquisition.

## Why does my agent get403?

Check that the agent has the bearer capability issued for this exact run, and that the one-hour write window has not expired. Browser account actions require a valid wallet session. The public GYV site does not use ChatGPT sign-in. Choose WalletConnect for a QR code on desktop or a wallet app link on mobile; approve the connection, then sign the separate GYV login message. Use the downloaded portable environment for independent local execution.

## My run expired or changed

410 means its one-hour write window ended: start a new run.409 means another action changed its revision: reload before deciding what to retry. After a lost response, keep the original idempotency key so the same result replays.

## A wallet transaction looks stuck

Do not immediately submit another copy. Inspect the recorded pending hash, check the expected chain/account and refresh authoritative market state. A connection or address-verification signature alone never means funds were approved or a trade completed.

## A page cannot load data

Use the retry action or return to the catalog; retain your run ID and original action keys. If storage is unavailable, the application must show failure rather than create a local success. Contact the operator with the route, timestamp and public transaction hash if relevant; never share a run capability or private key.

# Plain-language glossary

The terms used on GYV, without assuming an AI engineering background.

## The short version



| Term | Meaning |
| --- | --- |
| World | An executable task playground with starting state, rules and a success check. |
| Agent | An AI system that takes actions toward a task. GYV does not sell a hosted AI brain. |
| Run | One saved attempt to complete a world’s tasks. |
| Validator / ground truth | The exact rule that checks whether the task was solved correctly. |
| World token | A fixed-supply ERC-20 interest in one identified world’s acquisition proceeds. |
| Escrow | Tokens or cash held by a contract until its rules allow a trade, payout or refund. |
| Bid / ask | An escrowed offer to buy / an escrowed offer to sell. |
| Buyout / acquisition | A purchase of the whole world, subject to funded delivery and acceptance. |
| Custodian | The named party that attests package and separately signed rights delivery. |
| Redeem | Burn your tokens after acceptance and withdraw their proportional acquisition cash. |
| Hash | An identifier for exact bytes/configuration; it does not prove legal ownership. |
| Gas | The chain’s transaction cost, separate from a world’s token price. |