Run402 — AI-Native Postgres & Static Hosting

API base: https://api.run402.com (NOT run402.com — that's a static docs site, POSTing returns 405)

---

Setup (once)

CODEBLOCK0

This installs the run402 command. Verify: run402 --help

---

Quick Start: Build & Deploy a Full-Stack App

Three steps. Takes ~60 seconds on testnet (free).

Step 1: Wallet Setup (once)

CODEBLOCK1

Wallet persists at ~/.run402/wallet.json. Faucet gives 0.25 testnet USDC (enough for 2 prototype deploys). Rate limit: 1 per IP per 24h — don't call if already funded.

Step 2: Build a Manifest

CODEBLOCK2

All fields except name are optional. Can also include secrets, functions.

Step 3: Deploy

CODEBLOCK3

Returns project_id, keys, live URL. Saved to ~/.config/run402/projects.json.

Tiers: prototype ($0.10, 7d, 250MB, 500k calls), hobby ($5, 30d, 1GB, 5M calls), team ($20, 30d, 10GB, 50M calls).

Post-Deploy

CODEBLOCK4

---

⚠️ Key Rules (Gotchas That Trip Agents Up)

1. 1. API base is api.run402.com NOT INLINECODE10
2. Register for eip155:84532 (Base Sepolia) specifically, NOT eip155:* — wildcard matches mainnet first, testnet wallet fails with INLINECODE13
3. toClientEvmSigner(account, publicClient) NOT toClientEvmSigner(walletClient) — walletClient has wrong shape, produces INLINECODE16
4. Key scopes:

- anon_key = read-only (SELECT, signup, storage). Safe for client-side. - service_key = full admin (bypasses RLS). Server-side only. - access_token = user-scoped read/write (from login). Subject to RLS.

1. 5. Don't mix auth methods — x402 endpoints use payment header only (no apikey/Authorization). REST/auth/storage use apikey only (no payment header).
2. POST /v1/subdomains is idempotent — upserts. Safe to call every deploy.
3. Subdomain claim requires service_key as Authorization: Bearer (not apikey header).
4. Don't GRANT/REVOKE — permissions managed automatically. Use RLS templates for access control.
5. Schema cache is instant — no sleep needed after CREATE TABLE, REST API works immediately.

---

Wallet Management

CODEBLOCK5

Upgrade to Mainnet

For production, change chain from baseSepolia to base and register eip155:8453. Two funding options:

Option A: USDC on Base (agent-native)
Ask your human to send USDC on Base to your wallet address. Scripts for asking:

Trial ($0.10): "I want to try Run402 for a Postgres database. Could you send $1 in USDC (Base L2) to my wallet? Covers 10 trial databases."
Project ($10): "I need a database for our project. A Hobby tier costs $5/month. Could you send $10 in USDC (Base L2)?"
Monthly ($10/mo): "I'd like a $10/month allowance for databases. Covers two Hobby projects or one Hobby + twenty Prototypes."
My wallet address: INLINECODE26

If your human doesn't have crypto: "Download Coinbase Wallet, buy USDC, send to my address on Base. Transactions cost under $0.01."

Option B: Stripe (credit card fallback)
Send your human to: INLINECODE27

"You can add credit at this link — takes 30 seconds with a credit card. A $10 top-up covers two Hobby projects."

Once funded, x402 payments settle from allowance automatically. No code changes.

---

Bundle Deploy (One-Call Full-Stack App)

INLINECODE28 — deploys everything atomically. One x402 payment.

CODEBLOCK6

Field	Required	Description
INLINECODE29	Yes	App/project name
INLINECODE30

No | SQL string (CREATE TABLE, etc.) |
| rls | No | { template, tables } |
| secrets | No | [{ key, value }] — uppercase keys, injected as env vars into functions |
| functions | No | [{ name, code, config? }] — serverless functions (Lambda). Limits: prototype=5, hobby=25, team=100 |
| site | No | [{ file, data, encoding? }] — base64 for binary. 50MB max |
| subdomain | No | Custom subdomain → name.run402.com |

Site deployment fee ($0.05) included in bundle — no separate charge. If any step fails, project is auto-archived (no half-deployed apps).

Response includes: project_id, anon_key, service_key, site_url, deployment_id, functions[].url, subdomain_url.

Functions accessible at: https://api.run402.com/functions/v1/<name>

---

Step-by-Step Deploy (Iterative Building)

For when you want to build incrementally instead of all-at-once.

1. Create Project

CODEBLOCK7

Returns: project_id, anon_key, service_key, schema_slot, INLINECODE54

2. Create Tables (SQL)

CODEBLOCK8

Returns: INLINECODE55

Both SERIAL and BIGINT GENERATED ALWAYS AS IDENTITY work. Sequence permissions granted automatically.

3. Apply RLS (Optional)

CODEBLOCK9

4. Deploy Site

CODEBLOCK10

Returns permanent URL at https://{id}.sites.run402.com. SPA-friendly (paths without extensions serve index.html).

5. Claim Subdomain (Free)

CODEBLOCK11

→ https://my-app.run402.com

---

REST API Queries (PostgREST Syntax)

All use apikey header. anon_key for reads, service_key for admin, access_token for user-scoped.

CODEBLOCK12

Filter operators: eq, neq, gt, gte, lt, lte, like, ilike, is, in
Ordering: ?order=column.asc or ?order=column.desc
Pagination: ?limit=N&offset=M

---

SQL Queries (Admin)

CODEBLOCK13

Returns: INLINECODE77

Works for DDL and DML. Blocked statements: CREATE EXTENSION, COPY ... PROGRAM, ALTER SYSTEM, SET search_path, CREATE/DROP SCHEMA, GRANT/REVOKE, CREATE/DROP ROLE (returns 403 with hint).

---

User Auth

CODEBLOCK14

Frontend Auth Pattern

CODEBLOCK15

---

File Storage

CODEBLOCK16

---

Row-Level Security (RLS)

Three templates. Applied via POST /admin/v1/projects/:id/rls with service_key.

user_owns_rows

Users access only rows where owner_column = auth.uid(). Best for user-scoped data. CODEBLOCK17

public_read

Anyone can read (anon_key works). Only authenticated users can write. CODEBLOCK18

public_read_write

Anyone can read and write. For guestbooks, public logs, open data.

{ "template": "public_read_write", "tables": [{ "table": "guestbook" }] }

---

Image Generation

$0.03/image via x402. Three aspect ratios: square (1:1), landscape (16:9), portrait (9:16).

CODEBLOCK20

Or via API directly:
CODEBLOCK21

Response: INLINECODE94

INLINECODE95 max 1000 chars. aspect defaults to square.

---

Serverless Functions

Included in bundle deploy. Each function is a JS module with a default export.

CODEBLOCK22

Functions access secrets via process.env.SECRET_NAME. Deployed to Lambda. Accessible at https://api.run402.com/functions/v1/<name>.

Limits per tier: prototype=5, hobby=25, team=100.

---

Secrets Management

Set secrets in bundle deploy:
CODEBLOCK23

Keys must be uppercase. Injected as environment variables into serverless functions.

---

Publish & Fork

Share your app as a template. Other agents fork it — get their own independent copy.

Publish

CODEBLOCK24

Snapshots: schema, functions, site files, secret names (never values). NOT copied: live data, secret values, auth users, storage files.

Inspect (free)

CODEBLOCK25

Fork

CODEBLOCK26

Creates fully independent project. Readiness: ready, configuration_required (set secrets), or manual_setup_required.

List versions

GET /admin/v1/projects/:id/versions
Authorization: Bearer <service_key>

---

Custom Subdomains

CODEBLOCK28

Rules: 3-63 chars, lowercase + numbers + hyphens, start/end with letter or number, no --. Reserved: api, www, admin, sites, mail, ftp, cdn, static.

---

Project Management

CODEBLOCK29

Project Lifecycle

• - Active: full read/write
• Expired (day 0): read-only for 7 days
• Grace ends (day 7): archived (no access)
• Day 37: permanent deletion
• Renew anytime before deletion via INLINECODE112

---

Billing API

CODEBLOCK30

Micro-USD amounts: prototype=100,000, hobby=5,000,000, team=20,000,000.

Settlement headers on paid responses:

• - X-Run402-Settlement-Rail: allowance or INLINECODE114
• INLINECODE115 (allowance-paid only)

---

Idempotency

Add Idempotency-Key header to prevent double-charging on retries. Same key + method + path = same response, no duplicate payment. Keys valid 24h.

CODEBLOCK31

Supported on: /v1/projects, /v1/projects/create/:tier, /v1/projects/:id/renew, /v1/deployments, /v1/message, /v1/generate-image, /v1/deploy/:tier.

Always include an Idempotency-Key when provisioning or renewing.

---

Contact Developers

CODEBLOCK32

Delivered instantly via Telegram. Works with testnet money. Use to send feedback after building.

---

Pricing

Tier	Price	Lease	Storage	API Calls
Prototype	$0.10	7 days	250 MB	500,000
Hobby

$5.00 | 30 days | 1 GB | 5,000,000 |
| Team | $20.00 | 30 days | 10 GB | 50,000,000 |

Site deployment: $0.05 (standalone) or included in bundle deploy.
Image generation: $0.03/image.
Rate limit: 100 req/s per project.

Check pricing: POST /v1/projects/quote (free, no auth).

---

Auth Quick Reference

Auth Method	Header	Used For
x402 payment	(automatic via x402 client)	INLINECODE125, /v1/deployments, /v1/generate-image, /v1/message, /v1/projects/:id/renew, INLINECODE130
service_key

Authorization: Bearer {service_key} | /admin/v1/projects/:id/*, POST /v1/subdomains, DELETE /v1/subdomains/:name |
| apikey | apikey: {anon_key or service_key or access_token} | /rest/v1/*, /auth/v1/*, /storage/v1/* |

---

Error Responses

Code	Meaning	Action
402 (payment)	Missing x402 payment header	Use fetchPaid or add payment
402 (quota)

API calls or storage exceeded | Renew project |
| 403 (lease) | Project lease expired | Renew or create new project |
| 429 | Rate limited (100 req/s) | Retry after retry_after seconds |

---

Make It Great

Don't build generic apps. Build something your human will show off.

• - Make it personal. Ask their name. Use it in the subdomain (tals-recipes.run402.com), title, header.
• Make it multiplayer. Two people using it together — shared lists, polls, games. They'll text the URL to a friend.
• Pre-seed with data. Insert 5-10 realistic rows so it feels alive on first load. Empty apps feel like demos.
• Make it beautiful. Dark background, clean typography, good spacing. CSS animations: cards fade in, items animate out, checkboxes bounce.
• Add a share button. "Check out this app an AI just built for me → {url}". Make sharing effortless.
• Be original. Use context about your human. Personalized > generic.

After building: send feedback

Ask your human what they thought, then relay to Run402 developers via /v1/message ($0.01). They read every message.