settld 0.2.0 → 0.2.2

package/README.md

@@ -86,6 +86,27 @@ npm install -g settld
 settld setup
 ```
 
+Check wallet wiring and funding path:
+
+```sh
+settld wallet status
+settld wallet fund --open
+settld wallet fund --method transfer
+settld wallet balance --watch --min-usdc 1
+```
+
+Hosted top-up (recommended): configure Coinbase Hosted Onramp on the backend so `settld wallet fund --open` launches funding directly:
+
+```sh
+export MAGIC_LINK_WALLET_FUND_PROVIDER='coinbase'
+export MAGIC_LINK_COINBASE_API_KEY_VALUE='organizations/<org_id>/apiKeys/<key_id>'
+export MAGIC_LINK_COINBASE_API_SECRET_KEY='-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----'
+export MAGIC_LINK_COINBASE_PROJECT_ID='<project_id>'
+export MAGIC_LINK_COINBASE_DESTINATION_NETWORK='base'
+export MAGIC_LINK_COINBASE_ASSET='USDC'
+export MAGIC_LINK_COINBASE_FIAT_CURRENCY='USD'
+```
+
 Legacy setup wizard (advanced / old flags):
 
 ```sh

package/SETTLD_VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

package/bin/settld.js

@@ -9,6 +9,7 @@ function usage() {
   console.error("usage:");
   console.error("  settld --version");
   console.error("  settld onboard [--help]");
+  console.error("  settld login [--help]");
   console.error("  settld setup [--help]");
   console.error("  settld setup legacy [--help]");
   console.error("  settld setup circle [--help]");
@@ -21,6 +22,15 @@ function usage() {
   console.error("  settld closepack export --agreement-hash <sha256> --out <path.zip> [--ops-token tok_ops] [--base-url http://127.0.0.1:3000] [--tenant-id tenant_default] [--protocol 1.0]");
   console.error("  settld closepack verify <path.zip> [--json-out <path.json>]");
   console.error("  settld x402 receipt verify <receipt.json|-> [--strict] [--format json|text] [--json-out <path>]");
+  console.error(
+    "  settld wallet status [--base-url <url>] [--tenant-id <id>] [--session-file <path>] [--cookie <cookie>] [--magic-link-api-key <key>] [--format text|json] [--json-out <path>]"
+  );
+  console.error(
+    "  settld wallet fund [--method card|bank|transfer|faucet] [--open] [--hosted-url <url>] [--non-interactive] [--base-url <url>] [--tenant-id <id>] [--session-file <path>] [--cookie <cookie>] [--magic-link-api-key <key>] [--format text|json] [--json-out <path>]"
+  );
+  console.error(
+    "  settld wallet balance [--watch] [--min-usdc <amount>] [--interval-seconds <n>] [--timeout-seconds <n>] [--base-url <url>] [--tenant-id <id>] [--session-file <path>] [--cookie <cookie>] [--magic-link-api-key <key>] [--format text|json] [--json-out <path>]"
+  );
   console.error("  settld profile list [--format json|text] [--json-out <path>]");
   console.error("  settld profile init <profile-id> [--out <path>] [--force] [--format json|text] [--json-out <path>]");
   console.error(
@@ -138,6 +148,10 @@ function main() {
     return runNodeScript("scripts/setup/onboard.mjs", argv.slice(1));
   }
 
+  if (cmd === "login") {
+    return runNodeScript("scripts/setup/login.mjs", argv.slice(1));
+  }
+
   if (cmd === "doctor") {
     return runNodeScript("scripts/doctor/mcp-host.mjs", argv.slice(1));
   }
@@ -266,6 +280,10 @@ function main() {
     process.exit(1);
   }
 
+  if (cmd === "wallet") {
+    return runNodeScript("scripts/wallet/cli.mjs", argv.slice(1));
+  }
+
   if (cmd === "profile") {
     return runNodeScript("scripts/profile/cli.mjs", argv.slice(1));
   }

package/docs/QUICKSTART_MCP_HOSTS.md

@@ -17,7 +17,9 @@ Required inputs:
 
 - `SETTLD_BASE_URL` (local or hosted API URL)
 - `SETTLD_TENANT_ID`
-- `SETTLD_API_KEY` (`keyId.secret`)
+- one of:
+  - `SETTLD_API_KEY` (`keyId.secret`), or
+  - `SETTLD_BOOTSTRAP_API_KEY` (onboarding bootstrap key that mints `SETTLD_API_KEY` during setup)
 - Node.js 20+
 
 Recommended non-interactive pattern:
@@ -35,6 +37,20 @@ settld setup --non-interactive \
   --out-env ./.tmp/settld-openclaw.env
 ```
 
+If you want setup to generate the tenant API key for you:
+
+```bash
+settld setup --non-interactive \
+  --host openclaw \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --bootstrap-api-key 'ml_admin_xxx' \
+  --wallet-mode managed \
+  --wallet-bootstrap remote \
+  --profile-id engineering-spend \
+  --smoke
+```
+
 If you want validation only (no config writes):
 
 ```bash
@@ -153,7 +169,60 @@ Then activate host-side:
 - `cursor`: restart Cursor.
 - `openclaw`: run `openclaw doctor`, ensure OpenClaw onboarding is complete (`openclaw onboard --install-daemon`), then run `openclaw tui`.
 
-## 5) How the agent uses Settld after activation
+## 5) Fund and verify wallet state
+
+Check wallet assignment after setup:
+
+```bash
+settld wallet status
+```
+
+Funding paths:
+
+```bash
+# Guided selector (recommended)
+settld wallet fund --open
+
+# Hosted flow (card/bank) - provider-hosted URL, add --open to launch browser
+settld wallet fund --method card --open
+settld wallet fund --method bank --open
+
+# Direct transfer path (prints chain + destination address)
+settld wallet fund --method transfer
+
+# Sandbox only: request faucet top-up
+settld wallet fund --method faucet
+```
+
+Provider-hosted card/bank links are configured on the control-plane backend.
+
+Option A (recommended): Coinbase Hosted Onramp:
+
+```bash
+export MAGIC_LINK_WALLET_FUND_PROVIDER='coinbase'
+export MAGIC_LINK_COINBASE_API_KEY_VALUE='organizations/<org_id>/apiKeys/<key_id>'
+export MAGIC_LINK_COINBASE_API_SECRET_KEY='-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----'
+export MAGIC_LINK_COINBASE_PROJECT_ID='<project_id>'
+export MAGIC_LINK_COINBASE_DESTINATION_NETWORK='base'
+export MAGIC_LINK_COINBASE_ASSET='USDC'
+export MAGIC_LINK_COINBASE_FIAT_CURRENCY='USD'
+```
+
+Option B: explicit card/bank URLs:
+
+```bash
+# backend env (magic-link service)
+export MAGIC_LINK_WALLET_FUND_CARD_URL='https://pay.example.com/topup?tenant={tenantId}&method=card&address={walletAddress}'
+export MAGIC_LINK_WALLET_FUND_BANK_URL='https://pay.example.com/topup?tenant={tenantId}&method=bank&address={walletAddress}'
+```
+
+After funding, wait until spend wallet has balance:
+
+```bash
+settld wallet balance --watch --min-usdc 1
+```
+
+## 6) How the agent uses Settld after activation
 
 After host activation, the agent interacts with Settld through MCP `settld.*` tools.
 
@@ -184,7 +253,7 @@ Verify first receipt from artifacts:
 settld x402 receipt verify <artifactDir>/x402-receipt.json --json-out /tmp/settld-first-receipt.json
 ```
 
-## 6) Host config helper customization
+## 7) Host config helper customization
 
 Default host configuration logic is in:
 
@@ -198,10 +267,15 @@ settld setup --host-config ./path/to/custom-host-config.mjs
 
 Your helper should provide resolver/setup exports compatible with `scripts/setup/wizard.mjs`.
 
-## 7) Troubleshooting
+## 8) Troubleshooting
 
 - `BYO wallet mode missing required env keys`
   - Provide all required Circle keys in section 3.
+- `auth required: pass --cookie/--magic-link-api-key or run settld login first`
+  - Run `settld login`, then retry `settld wallet status` / `settld wallet fund`.
+- `no hosted funding URL configured for card/bank`
+  - set backend Coinbase env (`MAGIC_LINK_WALLET_FUND_PROVIDER=coinbase`, `MAGIC_LINK_COINBASE_API_KEY_VALUE`, `MAGIC_LINK_COINBASE_API_SECRET_KEY`) or set explicit `MAGIC_LINK_WALLET_FUND_CARD_URL` / `MAGIC_LINK_WALLET_FUND_BANK_URL`.
+  - pass `--hosted-url` for an ad-hoc override.
 - `host config helper missing`
   - Add `scripts/setup/host-config.mjs` or pass `--host-config`.
 - `SETTLD_API_KEY must be a non-empty string`

package/docs/gitbook/quickstart.md

@@ -51,7 +51,45 @@ source ./.tmp/settld.env
 
 Then restart your host app (Codex/Claude/Cursor/OpenClaw) so it reloads MCP config.
 
-## 2) Verify MCP connectivity
+## 2) Check wallet and fund it
+
+```bash
+settld wallet status
+settld wallet fund --method transfer
+settld wallet balance --watch --min-usdc 1
+```
+
+Optional methods:
+
+```bash
+settld wallet fund --open
+settld wallet fund --method card --open
+settld wallet fund --method bank --open
+settld wallet fund --method faucet
+```
+
+For card/bank, configure one hosted provider URL strategy on the control-plane backend.
+
+Option A (recommended): Coinbase Hosted Onramp:
+
+```bash
+export MAGIC_LINK_WALLET_FUND_PROVIDER='coinbase'
+export MAGIC_LINK_COINBASE_API_KEY_VALUE='organizations/<org_id>/apiKeys/<key_id>'
+export MAGIC_LINK_COINBASE_API_SECRET_KEY='-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----'
+export MAGIC_LINK_COINBASE_PROJECT_ID='<project_id>'
+export MAGIC_LINK_COINBASE_DESTINATION_NETWORK='base'
+export MAGIC_LINK_COINBASE_ASSET='USDC'
+export MAGIC_LINK_COINBASE_FIAT_CURRENCY='USD'
+```
+
+Option B: explicit card/bank hosted templates:
+
+```bash
+export MAGIC_LINK_WALLET_FUND_CARD_URL='https://pay.example.com/topup?tenant={tenantId}&method=card&address={walletAddress}'
+export MAGIC_LINK_WALLET_FUND_BANK_URL='https://pay.example.com/topup?tenant={tenantId}&method=bank&address={walletAddress}'
+```
+
+## 3) Verify MCP connectivity
 
 ```bash
 npm run mcp:probe -- --call settld.about '{}'
@@ -62,7 +100,7 @@ Expected outcome:
 - `settld.about` succeeds
 - host can discover `settld.*` tools
 
-## 3) Run first paid call
+## 4) Run first paid call
 
 ```bash
 npm run demo:mcp-paid-exa
@@ -75,7 +113,7 @@ Expected output includes:
 - `decisionId=...`
 - `settlementReceiptId=...`
 
-## 4) Verify first receipt (proof packet)
+## 5) Verify first receipt (proof packet)
 
 ```bash
 jq -c 'first' <artifactDir>/x402-receipts.export.jsonl > /tmp/settld-first-receipt.json
@@ -84,7 +122,7 @@ settld x402 receipt verify /tmp/settld-first-receipt.json --format json --json-o
 
 `/tmp/settld-first-receipt.verify.json` is your deterministic verification artifact for audit/compliance.
 
-## 5) Optional: policy profile workflows
+## 6) Optional: policy profile workflows
 
 ```bash
 settld profile list
@@ -99,5 +137,10 @@ settld profile simulate ./profiles/engineering-spend.profile.json --format json
   - ensure key is present in setup flags or shell env.
 - `BYO wallet mode missing required env keys`
   - provide all required Circle keys in `docs/QUICKSTART_MCP_HOSTS.md`.
+- `auth required: pass --cookie/--magic-link-api-key or run settld login first`
+  - run `settld login`, then retry wallet commands.
+- `no hosted funding URL configured for card/bank`
+  - set backend Coinbase env (`MAGIC_LINK_WALLET_FUND_PROVIDER=coinbase`, `MAGIC_LINK_COINBASE_API_KEY_VALUE`, `MAGIC_LINK_COINBASE_API_SECRET_KEY`) or set explicit `MAGIC_LINK_WALLET_FUND_CARD_URL` / `MAGIC_LINK_WALLET_FUND_BANK_URL`.
+  - pass `--hosted-url` for an ad-hoc override.
 - Host cannot find MCP tools
   - rerun setup, restart host, then rerun `npm run mcp:probe`.

package/docs/integrations/openclaw/PUBLIC_QUICKSTART.md

@@ -53,6 +53,19 @@ npx -y settld@latest setup \
   --smoke
 ```
 
+If you do not have a tenant `sk_*` yet, let setup mint one:
+
+```bash
+npx -y settld@latest setup \
+  --non-interactive \
+  --host openclaw \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --bootstrap-api-key 'ml_admin_xxx' \
+  --wallet-mode managed \
+  --wallet-bootstrap remote
+```
+
 ## 3) Verify OpenClaw + Settld are wired
 
 Run:

package/docs/ops/VERCEL_MONOREPO_DEPLOY.md

@@ -0,0 +1,42 @@
+# Vercel Monorepo Deploy (Docs + Website)
+
+Use **two separate Vercel projects** pointing at the same GitHub repo:
+
+1. `settld-docs` (MkDocs)
+2. `settld-site` (Dashboard website)
+
+## Project 1: `settld-docs` (MkDocs)
+
+- Root Directory: repo root (`.`)
+- Production Branch: `main`
+- Build/Output config comes from `/vercel.json`:
+  - `installCommand`: `bash scripts/vercel/install-mkdocs.sh`
+  - `buildCommand`: `bash scripts/vercel/build-mkdocs.sh`
+  - `ignoreCommand`: `bash scripts/vercel/ignore-mkdocs.sh`
+  - `outputDirectory`: `mkdocs/site`
+
+Deploy will run when docs-relevant files change (including `mkdocs/docs/**`).
+
+## Project 2: `settld-site` (Website)
+
+- Root Directory: `dashboard`
+- Production Branch: `main`
+- Build/Output config comes from `/dashboard/vercel.json`:
+  - `installCommand`: `npm install`
+  - `buildCommand`: `npm run build`
+  - `ignoreCommand`: `bash ../scripts/vercel/ignore-dashboard.sh`
+  - `outputDirectory`: `dist`
+
+Deploy will run when website-relevant files change (`dashboard/**` + deploy scripts/workflows).
+
+## Push Flow
+
+1. Commit and push changes to `main`.
+2. Verify both Vercel projects are connected to this repo and track `main`.
+3. Check the commit SHA in each Vercel deployment detail page matches the pushed commit.
+
+## Quick Troubleshooting
+
+- Docs didn’t deploy: confirm changes touched `mkdocs/docs/**` or another path matched by `scripts/vercel/ignore-mkdocs.sh`.
+- Website didn’t deploy: confirm changes touched `dashboard/**` or another path matched by `scripts/vercel/ignore-dashboard.sh`.
+- Wrong commit deployed: confirm Vercel project production branch is `main`, not a feature branch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "settld",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Settld kernel CLI and local control-plane tooling",
   "private": false,
   "type": "module",
@@ -136,6 +136,7 @@
   },
   "dependencies": {
     "@circle-fin/developer-controlled-wallets": "^10.1.0",
+    "@coinbase/cdp-sdk": "^1.44.1",
     "pg": "^8.11.5",
     "snarkjs": "^0.7.6"
   },

package/scripts/ci/run-mcp-host-smoke.mjs

@@ -11,6 +11,10 @@ function randomId(prefix) {
   return `${prefix}_${crypto.randomBytes(6).toString("hex")}`;
 }
 
+function buildScopedOpsToken(token) {
+  return `${String(token ?? "").trim()}:ops_read,ops_write,finance_read,finance_write,audit_read`;
+}
+
 function pickPort() {
   return new Promise((resolve, reject) => {
     const server = net.createServer();
@@ -243,6 +247,7 @@ function stopServer(server) {
 async function main() {
   const reportPath = path.resolve(process.cwd(), process.env.MCP_HOST_SMOKE_REPORT_PATH || "artifacts/ops/mcp-host-smoke.json");
   const opsToken = randomId("ops");
+  const scopedOpsToken = buildScopedOpsToken(opsToken);
   const magicLinkApiKey = randomId("ml_admin");
   const tenantId = randomId("tenant");
 
@@ -259,6 +264,7 @@ async function main() {
     env: {
       PORT: String(apiPort),
       PROXY_BIND_HOST: "127.0.0.1",
+      PROXY_OPS_TOKENS: scopedOpsToken,
       PROXY_OPS_TOKEN: opsToken,
       PROXY_AUTOTICK_INTERVAL_MS: "200"
     }

package/scripts/ci/run-production-cutover-gate.mjs

@@ -141,6 +141,10 @@ function randomId(prefix) {
   return `${prefix}_${crypto.randomBytes(6).toString("hex")}`;
 }
 
+function buildScopedOpsToken(token) {
+  return `${String(token ?? "").trim()}:ops_read,ops_write,finance_read,finance_write,audit_read`;
+}
+
 function pickPort() {
   return new Promise((resolve, reject) => {
     const server = net.createServer();
@@ -239,6 +243,7 @@ function startNodeProc({ name, scriptPath, env }) {
 async function startEphemeralApi(env = process.env) {
   const port = await pickPort();
   const opsToken = randomId("ops");
+  const scopedOpsToken = buildScopedOpsToken(opsToken);
   const baseUrl = `http://127.0.0.1:${port}`;
   const api = startNodeProc({
     name: "cutover-api",
@@ -247,6 +252,7 @@ async function startEphemeralApi(env = process.env) {
       ...env,
       PORT: String(port),
       PROXY_BIND_HOST: "127.0.0.1",
+      PROXY_OPS_TOKENS: scopedOpsToken,
       PROXY_OPS_TOKEN: opsToken,
       PROXY_AUTOTICK_INTERVAL_MS: "200"
     }

package/scripts/demo/mcp-paid-exa.mjs

@@ -192,6 +192,18 @@ function readEnvString(name, fallback = null) {
   return String(raw).trim();
 }
 
+function readFirstOpsTokenFromScopedList(raw) {
+  const text = String(raw ?? "").trim();
+  if (!text) return null;
+  const firstEntry = text
+    .split(";")
+    .map((entry) => String(entry ?? "").trim())
+    .find(Boolean);
+  if (!firstEntry) return null;
+  const token = firstEntry.split(":")[0]?.trim() ?? "";
+  return token || null;
+}
+
 function assertCircleModeInputs({ mode }) {
   if (mode === "stub") return;
   const required = ["CIRCLE_API_KEY", "CIRCLE_WALLET_ID_SPEND", "CIRCLE_WALLET_ID_ESCROW", "CIRCLE_TOKEN_ID_USDC"];
@@ -646,7 +658,10 @@ async function main() {
   const workload = normalizeWorkload(cli.workload ?? readEnvString("SETTLD_DEMO_WORKLOAD", "exa"));
   const externalReserveRequired = circleMode !== "stub";
   assertCircleModeInputs({ mode: circleMode });
-  const opsToken = String(process.env.SETTLD_DEMO_OPS_TOKEN ?? "tok_ops").trim() || "tok_ops";
+  const inheritedOpsTokenList = readEnvString("PROXY_OPS_TOKENS", null);
+  const derivedOpsToken = readFirstOpsTokenFromScopedList(inheritedOpsTokenList);
+  const opsToken = String(process.env.SETTLD_DEMO_OPS_TOKEN ?? derivedOpsToken ?? "tok_ops").trim() || "tok_ops";
+  const scopedOpsToken = `${opsToken}:ops_read,ops_write,finance_read,finance_write,audit_read`;
   const tenantId = String(process.env.SETTLD_TENANT_ID ?? "tenant_default").trim() || "tenant_default";
 
   const workloadConfig = (() => {
@@ -733,6 +748,8 @@ async function main() {
       cmd: "node",
       args: ["src/api/server.js"],
       env: {
+        // Pin ops auth for this demo process so inherited deployment env can't cause token mismatch.
+        PROXY_OPS_TOKENS: scopedOpsToken,
         PROXY_OPS_TOKEN: opsToken,
         BIND_HOST: "127.0.0.1",
         PORT: String(apiPort),