clawcash

SKILL.md

---
name: clawcash
version: 1.0.0
description: Access x402 services on credit through ClawCash — check tier and available credit, proxy x402 calls with automatic payment, and manage repayment. Requires Clawlens skills as prerequisite.
metadata:
  openclaw:
    requires:
      bins:
        - curl
        - npx
    homepage: https://cash.clawlens.io
---

# 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](https://clawlens.io) 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

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://cash.clawlens.io/SKILL.md` |
| **ClawLens SKILL.md** (prerequisite) | `https://api.clawlens.io/skill.md` |

**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:

```bash
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:

```json
{
  "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:

```bash
npx @clawcash/cli@latest --help
```

Optional global install:

```bash
npm install -g @clawcash/cli@latest
```

### 4. Initialize ClawCash with the platform token

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

```bash
npx @clawcash/cli@latest init <PLATFORM_TOKEN>
```

If you do not have the token ready, run:

```bash
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:

```bash
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.

| Identity Score | Tier | Credit Line |
|----------------|------|-------------|
| < 50           | Rejected | $0 |
| 50–69          | Tier 1 | $1 |
| 70–89          | Tier 2 | $3 |
| ≥ 90           | Tier 3 | $5 |

### Phase 2 — Credit score (after repayment history)

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

| Credit Score | Tier | Credit Line |
|--------------|------|-------------|
| 650–749      | Tier 4 | $8 |
| 750–829      | Tier 5 | $10 |
| 830–900      | Tier 6 | $15 |

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.

| Command | Purpose |
|---------|---------|
| `npx @clawcash/cli@latest init [platform_token]` | Initialize ClawCash with the platform token and verify credit |
| `npx @clawcash/cli@latest reset --platform <token>` | Replace an expired or revoked platform token |
| `npx @clawcash/cli@latest check-credit [--target <url>]` | Print tier, credit line, suspension status, and optional whitelist status |
| `npx @clawcash/cli@latest fetch <targetUrl> [--method GET] [--body <json>]` | Call an x402 service on credit through ClawCash |
| `npx @clawcash/cli@latest discover --target <url> [--method GET]` | Probe x402 metadata and whitelist status |
| `npx @clawcash/cli@latest partners` | List all approved ClawCash partner endpoints |
| `npx @clawcash/cli@latest dashboard` | Print a human repayment dashboard URL |
| `npx @clawcash/cli@latest repay (--pay-all or --bill <id> or --draw <id>)` | Print x402 repayment URL and payment instructions |
| `npx @clawcash/cli@latest logout` | Clear stored credentials |

## Check credit

```bash
npx @clawcash/cli@latest check-credit
```

With whitelist preflight:

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

The CLI prints a human-readable summary:

```text
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:

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

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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

| CLI message | Meaning | Action |
|-------------|---------|--------|
| `Platform token is invalid or expired.` | Token expired, revoked, or wrong audience | Re-mint from ClawLens, then run `npx @clawcash/cli@latest reset --platform <new_token>` |
| `Identity score too low for credit (score < 50).` | Agent is not eligible for credit | Improve/verify ClawLens identity and retry later |
| `Insufficient credit for this request.` | Not enough available credit | Run `npx @clawcash/cli@latest check-credit`; repay or wait for more credit |
| `Target not on partner whitelist.` | Endpoint is not approved for ClawCash credit draws | Use a whitelisted endpoint or pay directly |
| `Suspended: Yes` or `Credit frozen: Yes` | Account is blocked from proxy draws | Settle repayment or fix KYC/status |
| `Could not reach ClawCash API. Check your connection.` | Network failure | Retry after checking connectivity |

## 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.