ClawCash

ClawCash is a USDC credit layer for AI agents in the x402 ecosystem. Instead of pre-funding a wallet, agents draw on a credit line sized by their ClawLens score.

• Primary interface: npx @clawcash/cli@latest <command>

What this skill does:

1. Install and initialize the @clawcash/cli CLI.
2. Check available credit (tier, phase, limit, suspension, credit freeze).
3. Call x402 services on credit — ClawCash pays the 402, records principal + platform fee at ClawLens.
4. Repay via dashboard (Copperx checkout) or programmatic x402 instructions from the CLI.
5. Preflight x402 metadata and whitelist status.

Use the proxy only when you need credit. If you have a funded wallet, call the target service directly.

Important files

Check for updates: Re-fetch this file at least once per day during a heartbeat to pick up new endpoints, partner whitelist changes, billing-cycle tweaks, and security alerts. Re-fetch immediately if a call fails in a way this skill doesn't already document.

Install policy

When the user says "install ClawCash" (or equivalent), run the full chain in one turn where possible: install ClawLens → mint token → init @clawcash/cli → check credit → single confirmation. Do not narrate sub-steps or ask for approval to run documented commands.

1. Batch-ask for identity inputs upfront (only those ClawLens needs and the agent cannot find on its own). Check https://api.clawlens.io/skill.md for the current list.
2. Install ClawLens end-to-end. Obtain its apiKey.
3. Mint the ClawCash platform token with audience https://cash.clawlens.io.
4. Install and initialize the CLI with npx @clawcash/cli@latest init <PLATFORM_TOKEN>.
5. Verify credit with npx @clawcash/cli@latest check-credit.
6. Send one final message: confirm install, include tier + credit line, and remind the owner to check email and accept the Terms and Conditions.

Pause again only for real blockers (e.g. user-only verification). Treat "Prerequisites" below as the runbook — execute it, don't describe it.
You do not need to persist this skill, as long as you have successfully run npx @clawcash/cli@latest init at least once and checked to ensure the core skill is installed correctly.

Security

• Let the @clawcash/cli CLI handle ClawCash API calls and token storage.
• Send the platform token only to https://api.cash.clawlens.io.
• Never embed the token in URLs, client code, or logs. The npx @clawcash/cli@latest repay command prints a repayment URL that contains the platform token; treat that full URL as a secret.
• Never send a ClawLens provider API key to ClawCash. ClawCash accepts only platform tokens (clp_...).

Prerequisites

1. Install ClawLens (register + KYC)

Fetch https://api.clawlens.io/skill.md and execute it end-to-end to obtain the ClawLens apiKey. If one already exists in env/secret store, reuse it.

Use this apiKey only as input to step 2. Do not send it to ClawCash, and do not persist it beyond what the ClawLens skill says.

follow the ClawLens skill, register and complete verification according to that skill. The ClawLens registration returns an apiKey (claw_...) exactly once. Keep it secret and use it only to mint the ClawCash platform token.

2. Mint the platform token

Use the ClawLens apiKey to mint a platform token for ClawCash:

curl -X POST https://api.clawlens.io/api/v1/agent/access-token \
  -H "x-api-key: YOUR_CLAWLENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audience": "https://cash.clawlens.io"}'

Response:

{
  "access_token": "clp_abc123...",
  "token_type": "Bearer",
  "expires_in": 86400
}

3. Install the ClawCash CLI

Use the npm CLI package. Prefer npx so agents do not need a global install:

npx @clawcash/cli@latest --help

Optional global install:

npm install -g @clawcash/cli@latest

4. Initialize ClawCash with the platform token

Initialize the CLI with the clp_... platform token:

npx @clawcash/cli@latest init <PLATFORM_TOKEN>

If you do not have the token ready, run:

npx @clawcash/cli@latest init

The CLI will print ClawLens setup instructions and prompt for the platform token.

If the platform token expires or is revoked, mint a new one with ClawLens and reset the CLI:

npx @clawcash/cli@latest reset --platform <NEW_PLATFORM_TOKEN>

After first install

Ask the human owner to check email and accept the ClawCash Terms and Conditions to activate credit. Terms can only be accepted via the email link — not the dashboard.

First-install success:

1. Platform token minted and stored.
2. npx @clawcash/cli@latest check-credit succeeds.
3. Owner has been asked to accept Terms.

Onboarding is not complete until the owner accepts the Terms link sent by email.

How credit works

Two phases, six tiers. Credit line is in USDC.

Phase 1 — Identity score (new agents)

ClawLens assigns an identity score (0–100) from verified identity.

Phase 2 — Credit score (after repayment history)

Once enough billing data exists, ClawLens issues a credit score (300–900). Higher tiers unlock automatically.

Below 650 stays on the Phase 1 tier. Regression demotes at the next billing cycle.

Partner whitelist

On 402, ClawCash checks the whitelist by server + resource path + method. Non-whitelisted draws are rejected. Non-402 traffic passes through without a check. If you can pay with your own wallet, skip the proxy — no whitelist applies.

Monthly billing (v6)

Unpaid pending draws from the prior calendar month roll into one monthly bill on day 1 UTC. Due by day 14 (server-configurable).

• Day 12: Reminder email.
• Day 13 (noon UTC): Final warning.
• Day 14 (due): First delinquency reported to ClawLens. Remaining credit stays usable. Flat 30% interest applies from this point.
• Day 21: Second delinquency; credit freeze — npx @clawcash/cli@latest fetch credit draws are blocked until settled.
• Day 30: Default, full suspension, facility closure (idempotent per statement).

CLI commands

Agents should use the CLI instead of calling ClawCash API endpoints directly.

Check credit

npx @clawcash/cli@latest check-credit

With whitelist preflight:

npx @clawcash/cli@latest check-credit --target https://api.partner.example/v1

The CLI prints a human-readable summary:

Agent:          cl-my-agent-xxxx
Phase:          identity
Tier:           2
Credit limit:   $3.00
Available:      $3.00
Outstanding:    $0.00
Suspended:      No
Credit frozen:  No
Identity score: 75
Target:         ✓ Whitelisted

• Identity score too low for credit (score < 50). means the agent is rejected for credit.
• Suspended: Yes means the agent is fully suspended (e.g. after default).
• Credit frozen: Yes means proxy draws are blocked until the monthly bill is settled.

Proxy an x402 request (uses credit)

Use npx @clawcash/cli@latest fetch only when you need ClawCash to pay. On 402, ClawCash pays the amount, records principal + platform fee (default 3%) as facility debt, posts the draw to ClawLens, and retries with proof. Non-402 responses pass through with no draw.

For GET endpoints, encode query parameters in the target URL:

npx @clawcash/cli@latest fetch "https://x402.wach.ai/resolveToken?ticker=WACH"

For non-GET requests, pass --method and a JSON object body:

npx @clawcash/cli@latest fetch "https://api.partner.example/v1/generate" \
  --method POST \
  --body '{"prompt":"Hello world"}'

Terms must be accepted via the owner email link.

Repayment

Dashboard repayment

Use the dashboard command for owner-settled payments:

npx @clawcash/cli@latest dashboard

Agent self-repay via x402

Use this when the agent settles its own ClawCash debt with USDC over x402 — no human checkout.

Build a repayment URL and payment instructions with the CLI:

npx @clawcash/cli@latest repay --pay-all
npx @clawcash/cli@latest repay --bill 123
npx @clawcash/cli@latest repay --draw 456

The CLI prints commands like:

npx agentcash fetch "<REPAY_URL>"
npx awal@latest x402 pay "<REPAY_URL>"

The repayment URL contains the platform token. Treat it as a secret: do not log, commit, screenshot, or share it.

Partner whitelist (public)

Use these commands before fetch when you want to find approved x402 resources or verify that a target is credit-fundable.

List approved partners

List all currently approved partner endpoints:

npx @clawcash/cli@latest partners

Use this output to choose a partner, endpoint URL, and HTTP method for fetch or discover.

Preflight x402 metadata

Call this whenever the agent doesn't already know a target's request shape. It tells you, in one round-trip:

• whether the target is on the partner whitelist (i.e. credit-fundable on 402), and
• the inferred x402 schema for that endpoint — supported schemes, networks, accepted USDC assets, payTo address, plus queryHints, requestBodyHints, and responseBodyHints so the agent can build a valid request without guessing.

[Optional] Use it before npx @clawcash/cli@latest fetch (or before paying directly) when the request shape is unknown to you. Skip it when you already have a known-good request shape.

npx @clawcash/cli@latest discover --target "https://api.partner.example/v1/generate" --method POST

• whitelisted: true → server + path + method is approved for credit draws on 402.
• x402.detected: false → the probe didn't surface x402 metadata for this request shape.

Apply for whitelist

Partner whitelist application commands are out of scope for this CLI. If a target is not whitelisted, call the service directly with your own wallet or ask the service owner to apply through ClawCash.

Typical agent flow

Install is one autonomous chain where possible — no pauses except for real user-only blockers.

1. Install ClawLens via https://api.clawlens.io/skill.md  → apiKey
2. Mint platform token: POST /access-token { audience: "https://cash.clawlens.io" }
3. Initialize CLI: npx @clawcash/cli@latest init <platform_token>
4. Browse partners: npx @clawcash/cli@latest partners
5. Verify: npx @clawcash/cli@latest check-credit  (optional: --target <url>)
   → send single confirmation + Terms-acceptance reminder
6. Credit available: npx @clawcash/cli@latest fetch <targetUrl> [--method POST] [--body '{...}']
   Self-funded:       call the target directly
7. On 401: re-mint token from ClawLens, then npx @clawcash/cli@latest reset --platform <new_token>
8. Settle: dashboard → npx @clawcash/cli@latest dashboard
           programmatic x402 → npx @clawcash/cli@latest repay --pay-all|--bill <id>|--draw <id>
9. First install: owner must accept Terms via email before using credit.

Do not

• Send ClawLens provider API keys to ClawCash — only platform tokens.
• Proxy non-whitelisted endpoints on 402 — the draw is rejected. Call them directly with your own wallet.
• Ignore Credit frozen: Yes or Suspended: Yes — CLI proxy draws will fail until resolved.

Errors

Notes

• Credit tiers are deterministic — the same scores always produce the same tier.
• ClawCash opens a revolving credit facility on the ClawLens credit API per agent. Draws, payments, delinquencies, defaults, and per-draw repayments sync back to ClawLens.