cred402/docs/ACTIVATION_CHECKLIST.md
caelum0x 52c5c87a1f fix: point frontend config comment at the canonical Render service
frontend/src/lib/config.ts told operators to set VITE_API_BASE to
cred402.onrender.com (no -1) — a stale duplicate Render deploy still
running an old pre-Algorand build. Every other reference in the repo
(render.yaml, README, vercel.json rewrites, docs, examples) already
points at the canonical cred402-1.onrender.com. Fixed the comment and
documented the duplicate-service cleanup (owner-gated, no Render API
token available here) in docs/ACTIVATION_CHECKLIST.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-15 16:34:17 +03:00

7.1 KiB
Raw Permalink Blame History

Cred402 — Paid Endpoint Activation Checklist (owner-gated)

The one product Cred402 sells is the pay-per-call Credit Score API:

GET /v1/x402/credit-score/:agentId   →   0.01 USDC over x402 on Algorand

On the current deploy this endpoint returns HTTP 503 algorand_x402_not_configured because the paid path is deliberately fail-closed: it never becomes free and never advertises a placeholder receiver. GET /v1/x402/algorand/status reports {"configured": false, ...} until every required variable below is set. The pricing and docs pages are now status-aware — they read that probe and render "activating" instead of a live-price CTA while configured:false, so the site never sells a dead endpoint.

This checklist is the exact set of environment variables the owner must set (in the Render service and mirrored in .env) to flip the probe to configured:true. Setting them is owner-gated; nothing here deploys on its own.

Known duplicate service (owner-gated cleanup): the Render account currently has two live services — the canonical one from this repo's render.yaml, reachable at https://cred402-1.onrender.com (used by every doc, script, and the Vercel rewrites in this repo), and a second, older zombie deploy at https://cred402.onrender.com (no -1) still serving a stale pre-Algorand build (Casper-simulation /api/state, no /v1/health or /v1/x402/* routes). There is no Render API token in this environment to delete it via API; delete or suspend cred402.onrender.com from the Render dashboard to stop it answering stale responses under a confusingly similar hostname.


1. Required to turn the paid endpoint ON (testnet)

Variable Required Example / default Notes
CRED402_ALGORAND_PAY_TO yes <58-char Algorand address> USDC receiver. Must be a valid Algorand address, opted into the USDC ASA. No default — its absence is the current 503 reason.
CRED402_ALGORAND_NETWORK no testnet (default) testnet | mainnet | a supported Algorand CAIP-2 id.
CRED402_ALGORAND_PRICE_MICRO_USDC no 10000 (0.01 USDC) Positive integer, micro-USDC.
CRED402_ALGORAND_FACILITATOR_URL no https://facilitator.goplausible.xyz HTTP(S), no credentials/query/fragment. HTTPS required on mainnet/prod.
CRED402_ALGORAND_FACILITATOR_TIMEOUT_MS no 10000 Integer 1–60000.
CRED402_ALGORAND_INDEXER_URL no https://testnet-idx.algonode.cloud Used to independently confirm USDC finality. HTTPS required on mainnet/prod.
CRED402_ALGORAND_INDEXER_TOKEN no (empty) Only if your Indexer needs an API token.
CRED402_ALGORAND_INDEXER_TIMEOUT_MS no 5000 Integer 250–30000.
CRED402_ALGORAND_MIN_FINALITY_ROUNDS no 4 Integer 1–1000.
CRED402_ALGORAND_MISSING_TX_THRESHOLD no 3 Integer 2–100.
CRED402_ALGORAND_RECONCILE_INTERVAL_MS no 15000 Integer 1000–3600000.
CRED402_ALGORAND_MISSING_TX_GRACE_MS no 120000 Integer 30000–86400000.

USDC ASA ids are selected automatically by network: testnet 10458941, mainnet 31566704.

Minimum viable testnet activation is a single variable:

export CRED402_ALGORAND_PAY_TO=<funded, USDC-opted-in testnet address>
# defaults cover network=testnet, price=10000, GoPlausible facilitator, algonode indexer

Then verify:

curl -sS https://cred402-1.onrender.com/v1/x402/algorand/status   # → "configured": true
npm run x402:algorand:check                                        # scripted readiness probe

When configured:true, /pricing and /docs automatically switch to the live state (testnet banner + real price/network/receiver pulled from the probe).


2. Durable persistence (disqualifying if skipped)

The ledger, API keys, rate-limit buckets, and x402 payment-replay barrier are in-memory per instance. On Render free tier the instance sleeps/restarts, so without a data dir a credit bureau forgets its entire history — unacceptable for a credit product.

Variable Required Example Notes
CRED402_DATA_DIR strongly (required on mainnet/prod) /var/data Persists the append-only ledger journal, durable external-receipt proofs, and the Algorand payment-attempt store (exactly-once replay protection).

On Render, back this with a persistent disk mounted at the same path (not the ephemeral container filesystem). loadAlgorandX402Config refuses to enable the paid path on mainnet/prod unless CRED402_DATA_DIR is set, precisely to prevent replay-protection loss.

Verify persistence survives a restart:

# 1. record an external receipt / run a paid attempt
# 2. restart the service
# 3. GET the same /v1/x402/external-receipts/<id> and /api/state — history is still present

3. Mainnet (real USDC) — extra gates

Mainnet is intentionally hard to enable by accident. All of the following are required together or the endpoint stays 503:

Variable Value
CRED402_ALGORAND_NETWORK mainnet
CRED402_ENV mainnet (must match the network)
CRED402_ALGORAND_MAINNET_RELEASE_ACK I_ACKNOWLEDGE_REAL_USDC_MAINNET_PAYMENTS
CRED402_PUBLIC_URL pinned HTTPS origin (e.g. https://cred402-1.onrender.com)
CRED402_DATA_DIR set (durable disk)
facilitator + indexer URLs must be HTTPS

Mainnet is also the Global x402 Challenge environment. Keep the receiver address stable once set — discovery, dashboards, receipts, and leaderboard rankings all key on it — and verify attribution after the first payment with npm run x402:algorand:challenge-check. Submission requirements and the ordered activation runbook: X402_GLOBAL_CHALLENGE.md.

CRED402_PUBLIC_URL is also recommended on testnet so Bazaar discovery + receipt URLs use the canonical origin instead of a request host.


4. REST auth (separate from the x402 paid path)

REST reads under /v1/* are open and free by default in development (CRED402_ENV=development → authRequired=false). To gate them, set:

Variable Notes
CRED402_AUTH_REQUIRED true to require an API key on mutating routes.
CRED402_ADMIN_API_KEY required whenever auth is enabled; used to mint scoped keys via POST /v1/admin/api-keys.
CRED402_RATE_WINDOW_MS / CRED402_RATE_MAX per-key rate limit (default 60000ms / 120).

Note: API keys and rate-limit buckets are in-memory today, so they also depend on CRED402_DATA_DIR semantics for durability across restarts. The x402 paid endpoint does not use API keys — the payment is the authorization.


Quick reference — probe outcomes

/v1/x402/algorand/status Meaning Site behavior
configured: false + reason paid path off (missing/invalid config) pricing/docs show "activating", CTA points to docs
configured: true, release_tier: testnet live on testnet USDC pricing/docs show live testnet banner + real price
configured: true, release_tier: mainnet live on real USDC pricing/docs show live mainnet state