settld 0.2.1 → 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/bin/settld.js

@@ -22,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(
@@ -271,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

@@ -169,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.
 
@@ -200,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:
 
@@ -214,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "settld",
-  "version": "0.2.1",
+  "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),

package/scripts/setup/onboard.mjs

@@ -1453,6 +1453,12 @@ export async function runOnboard({
       lines.push(`Settld: ${normalizedBaseUrl} (tenant=${tenantId})`);
       lines.push(`Wallet mode: ${config.walletMode}`);
       lines.push(`Wallet bootstrap mode: ${walletBootstrapMode}`);
+      if (config.walletMode !== "none") {
+        lines.push("Wallet next steps:");
+        lines.push("- settld wallet status");
+        lines.push("- settld wallet fund --method transfer");
+        lines.push("- settld wallet balance --watch --min-usdc 1");
+      }
       if (args.outEnv) lines.push(`Wrote env file: ${args.outEnv}`);
       if (args.reportPath) lines.push(`Wrote report: ${args.reportPath}`);
       lines.push("");
@@ -1557,6 +1563,14 @@ export async function runOnboard({
       lines.push(`${step}. ${row}`);
       step += 1;
     }
+    if (config.walletMode !== "none") {
+      lines.push(`${step}. Run \`settld wallet status\` to confirm wallet wiring.`);
+      step += 1;
+      lines.push(`${step}. Fund with \`settld wallet fund --method transfer\` (or \`--method card --open\` if hosted links are configured).`);
+      step += 1;
+      lines.push(`${step}. Confirm funds: \`settld wallet balance --watch --min-usdc 1\`.`);
+      step += 1;
+    }
     lines.push(`${step}. Run \`npm run mcp:probe\` for an immediate health check.`);
     stdout.write(`${lines.join("\n")}\n`);
   }

package/scripts/vercel/build-mkdocs.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-if [ ! -x ".vercel-venv/bin/mkdocs" ]; then
-  echo "MkDocs venv not found; running install step first..."
+if ! python3 -m mkdocs --version >/dev/null 2>&1; then
+  echo "MkDocs not found; running install step first..."
   bash scripts/vercel/install-mkdocs.sh
 fi
 
-.vercel-venv/bin/mkdocs build --strict --config-file mkdocs.yml
+python3 -m mkdocs build --strict --config-file mkdocs.yml

package/scripts/vercel/ignore-dashboard.sh

@@ -5,6 +5,9 @@ set -euo pipefail
 # - exit 0 => skip deployment
 # - exit 1 => continue with deployment
 
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
 if ! git rev-parse --verify HEAD^ >/dev/null 2>&1; then
   # No parent commit context available; build to stay safe.
   exit 1

package/scripts/vercel/install-mkdocs.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-python3 -m venv .vercel-venv
-.vercel-venv/bin/python -m pip install --upgrade pip setuptools wheel
-.vercel-venv/bin/pip install mkdocs mkdocs-material
+python3 -m pip install --break-system-packages --upgrade pip setuptools wheel
+python3 -m pip install --break-system-packages mkdocs mkdocs-material