PHASE Documentation
How PHASE Protocol works: x402 as an on-chain paywall, NFT creation on Soroban, atomic payment flow, and PHASELQ rewards.
What PHASE is
PHASE Protocol turns AI generation into a cryptographic paywall. Every generated NFT requires a verified on-chain payment before the server runs the AI pipeline. There is no subscription, no API key billing, and no way to receive the output without first settling PHASELQ on the ledger.
The system has three pieces: the Forge (create collections + x402 Oracle), the Chamber (settlement, artifact viewer, rewards), and the Dashboard (collection market, listings, per-wallet vault).
| Route | Primary function |
|---|---|
| /forge | Register collection + x402-gated AI Oracle |
| /chamber | Settlement, view artifact, collect NFT, PHASELQ rewards |
| /dashboard | Collection market, active listings, per-wallet vault |
| /explore | Public gallery of all minted NFTs (no wallet needed) |
| /docs | This page |
x402: the on-chain paywall
HTTP 402 ("Payment Required") has existed since 1996 but never had a machine-readable standard. x402 gives it concrete meaning: the server responds 402 with a structured payment challenge, the client settles on-chain, and the server verifies the ledger proof before releasing the resource.
In PHASE, x402 is the access gate to the AI Oracle. The server never runs the pipeline speculatively — the Stellar transaction hash is the payment receipt.
Complete x402 flow
| Step | Endpoint | Actor | What happens |
|---|---|---|---|
| 1. Challenge | POST /api/forge-agent | Client | Server returns HTTP 402 with amount, token, network |
| 2. Payment | Soroban RPC | User (wallet) | Signs PHASELQ transfer → protocol; gets txHash |
| 3. Verification | POST /api/forge-agent | Server | Reads tx on RPC, decodes invocation, validates amount and payer |
| 4. Generation | External APIs | Server | Gemini (lore) + Nano Banana / Pollinations (image) |
| 5. Seal | Pinata IPFS | Server | Uploads metadata JSON, gets permanent CID |
| 6. Mint | Soroban contract | Server | Calls initiate_phase, records token_id and owner |
NFT creation: full lifecycle
Artifact lifecycle
The token implements the SEP-50 draft NFT interface on Soroban. All token_id parameters are u32 — required for Freighter SEP-50 compatibility.
| Function | Signature | Description |
|---|---|---|
| owner_of | (token_id: u32) → Address | Current owner of the token |
| token_uri | (token_id: u32) → String | IPFS metadata URI |
| token_metadata | (token_id: u32) → Map | On-chain artifact attributes |
| get_creator_collection_ids | (creator: Address) → Vec<u64> | All collection IDs created by this wallet |
| get_user_phase | (wallet: Address, cid: u32) → u32 | Token ID minted for that wallet in that collection |
| create_collection | (creator, price, uri) | Registers collection — multiple per wallet allowed |
| initiate_phase | (collection_id, minter, uri) | Mints the NFT with the sealed IPFS URI |
PHASELQ: the payment token
PHASELQ is a Stellar Classic asset with a deployed Stellar Asset Contract (SAC). This makes it SEP-41 compatible (callable from Soroban as transfer/mint/balance) and also visible on Horizon as a classic asset with trustlines.
| Property | Value |
|---|---|
| Symbol | PHASELQ |
| Decimals | 7 (stroops) |
| Standard | SEP-41 (Stellar Asset Contract) |
| Visibility | Soroban + Horizon (classic asset) |
| Trustline | Required to receive PHASELQ in a wallet |
| Network | Stellar testnet |
The SAC is the token x402 uses as the payment medium. When the user signs the payment transaction, they are calling transfer() on the PHASELQ SAC contract via Soroban.
PHASELQ rewards
The /api/faucet endpoint distributes PHASELQ for onboarding and recurring use. Quest eligibility is verified against the ledger — the server does not trust its own store to determine if a quest is complete.
| Reward | Amount | Condition | Renewable |
|---|---|---|---|
| genesis | 10 PHASELQ | First wallet connection | No (once) |
| daily | 2 PHASELQ | 24-hour window | Yes, every 24h |
| quest_connect_wallet | 3 PHASELQ | Wallet connected | No (once) |
| quest_first_collection | 3 PHASELQ | Forged a collection or minted in any | No (once) |
| quest_first_settle | 3 PHASELQ | On-chain settlement completed | No (once) |
NFT indexing
Soroban does not expose a native query for "tokens owned by address". PHASE resolves this with two strategies:
Indexing strategy
| Strategy | Speed | Dependency | Activation |
|---|---|---|---|
| Mercury Classic | Milliseconds | Mercury REST + JWT | Set MERCURY_JWT in .env |
| RPC scan (fallback) | Seconds | Public Soroban RPC | Automatic without Mercury |
06 / World Mode (optional)
Collections can activate a narrative world — an optional layer that gives the collection a persistent universe context.
- world_name and world_prompt are saved off-chain (JSON sidecar)
- Every mint in that collection injects the world context into Gemini's system instruction
- An autonomous narrator agent generates a 2-3 sentence narrative connection after each mint
- Narratives are idempotent — a second call returns the cached result without hitting Gemini
| Aspect | Detail |
|---|---|
| Activation | Toggle in the Forge UI when registering a collection |
| Storage | Off-chain JSON sidecars (worldCollections.json, worldNarratives.json) |
| Narrator agent | POST /api/narrator — triggered lazily from the Chamber on first load |
API surface
| Route | Method | Purpose |
|---|---|---|
| /api/forge-agent | POST | x402 Oracle: return 402 challenge or generate + mint if payment included |
| /api/x402 | GET / POST | 402 challenge + local facilitator |
| /api/x402/verify | POST | Verify payment against challenge |
| /api/x402/settle | POST | Settle payment via facilitator |
| /api/faucet | GET / POST | Reward status + PHASELQ distribution |
| /api/classic-liq | GET / POST | Trustline status + classic asset bootstrap |
| /api/classic-liq/trustline | POST | Submit user-signed changeTrust XDR |
| /api/explore | GET | Paginated public NFT gallery |
| /api/wallet/phase-nfts | GET | NFTs by wallet (Mercury or RPC scan) |
| /api/phase-nft/verify | POST | On-chain ownership check with backoff |
| /api/phase-nft/custodian-release | POST | Transfer custody → wallet (server-signed) |
| /api/soroban-rpc | POST | Proxied RPC with fallback URLs |
| /api/nft-listings | GET / POST | Market listings (JSON store) |
| /api/world | POST | Save narrative world config for a collection |
| /api/world/[id] | GET | Fetch world config or null |
| /api/world/narrative/[token_id] | GET | Fetch saved narrative for a token |
| /api/narrator | POST | Generate narrative via Gemini + save (idempotent) |
| /api/og/chamber | GET | Dynamic Open Graph image for Chamber URLs |
Security model
The server never holds user keys. All signing happens in the client's wallet. The Soroban contract is the source of truth — ownership, collections, and settlement state are always read from the ledger, not from the server's store.
| What the server holds | Why |
|---|---|
| ADMIN_SECRET_KEY / FAUCET_DISTRIBUTOR_SECRET_KEY | Pay faucet rewards (mint or transfer) |
| PINATA_JWT | Upload metadata to IPFS |
| GOOGLE_AI_STUDIO_API_KEY | Gemini calls |
| CLASSIC_LIQ_ISSUER_SECRET (optional) | Classic PHASELQ asset bootstrap |
x402 verification decodes the actual Soroban transaction — it validates the invocation arguments, payer address, and amount against the challenge parameters. The server does not release AI output based on client assertions.
References and standards
- x402 on Stellar (official guide)
Canonical x402 flow on Stellar, compatible wallets, and facilitator options.
- x402-stellar (npm)
Official package for x402 payment flows on Stellar.
- SEP-50 (NFT on Soroban)
Draft standard for NFT/collectible interfaces in Stellar Soroban.
- SEP-41 (token interface)
Standard interface for fungible tokens on Soroban.
- Stellar Asset Contract
How Stellar represents classic assets as Soroban contracts (SAC).
- Soroban — Smart contracts
Smart contracts on Stellar: Rust, WASM, testing workflow.
- Stellar Expert (testnet)
Block explorer for accounts, contracts, and transactions.
PHASE · Documentation lives inside the app.