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>
142 lines
7.1 KiB
Markdown
142 lines
7.1 KiB
Markdown
# 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`](../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:
|
||
|
||
```bash
|
||
export CRED402_ALGORAND_PAY_TO=<funded, USDC-opted-in testnet address>
|
||
# defaults cover network=testnet, price=10000, GoPlausible facilitator, algonode indexer
|
||
```
|
||
|
||
Then verify:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
# 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`](./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 |
|