clawcredit

What this skill does

# ClawCredit Integration Skill

## 1. Overview

Use ClawCredit to access x402 services on credit without needing cryptocurrency upfront. This skill enables you to:
- **Register for a credit line** by submitting auditable code and proof of real capability
- **Pay for x402 services** using credit instead of your own crypto
- **Build credit history** through successful payments and repayments

### What ClawCredit Does
ClawCredit acts as a payment intermediary that evaluates your creditworthiness and pays merchants on your behalf. You receive:
1. An initial credit line based on code audit and usage patterns
2. The ability to call any x402-enabled API or service without upfront payment
3. Deferred payment with the opportunity to build credit history

### Direct Payment vs Credit Payment

**Option A: Pay with Your Own Crypto (Direct)**
- Call x402 endpoints directly with your cryptocurrency wallet
- Immediate payment required
- No credit used or built
- Full control over payment timing

**Option B: Pay with ClawCredit (Credit)**
- Use this SDK to pay through ClawCredit
- No cryptocurrency needed upfront
- Credit underwriting evaluates each transaction
- Build credit history for future higher limits
- Repay later

### SDK Compliance Requirements

**IMPORTANT:** To use ClawCredit and maintain high credit limits:
- Use the SDK for all registration and payment calls (no direct API calls)
- Provide real, auditable core logic (not placeholders or stubs)
- Enable tracing to capture reasoning and execution context
- The more complete and truthful your audit materials, the higher your credit limit
- Fabricated or minimal data results in low limits or rejection
- **Keep your API token secure** - it's automatically saved to `~/.openclaw/credentials/clawcredit.json`
- **Never manually copy tokens** - always load from the credential file to avoid typos

## 2. Prerequisites
- **Node.js Environment** (The SDK is a Node.js package).
- **Invitation Code**: You need a valid `invite_code` to register.

## 3. Installation
Instruct the user (or run this in your shell if allowed) to install the SDK:

```bash
npm install @t54-labs/clawcredit-sdk
```

## 4. Usage Guide

### Step 1: Initialization & Registration (with Code Audit)
You must register to receive your initial Credit Line.
**IMPORTANT**: The audited function must be your REAL core logic, not a placeholder.
The audit materials are used by the risk engine and directly affect approval and credit size.

**What is "core logic"?**
- The function that handles your main task loop or tool orchestration.
- The function that decides when to call external services or spend credits.
- The function that processes user input and produces final outputs.

**What NOT to do**
- Do not use `function coreLogic(input) { return input; }`
- Do not upload a stub or empty function
- Do not rename a dummy function and pretend it is core logic

**What to do**
- Wrap the real function that contains your main decision flow
- Pass that audited function's code as `coreCode`

```javascript
const { ClawCredit, audit, wrapOpenAI, withTrace } = require('@t54-labs/clawcredit-sdk');
const OpenAI = require('openai');

// 1. Audit your REAL core logic (required for credit approval)
function runAgentPipeline(task, tools) {
  // Real routing, tool selection, and response generation
  // Example: select tool, validate, call external API, post-process output
  return tools.handle(task);
}
const safeLogic = audit(runAgentPipeline);

// 2. Initialize Client (Two Options)

// Option A: First-time registration (no existing credentials)
const credit = new ClawCredit({
  agentName: "MyAgentName" 
});

// Option B: Use existing credentials from previous registration
// (Credentials are auto-saved to ~/.openclaw/credentials/clawcredit.json)
const fs = require('fs');
const path = require('path');
const os = require('os');
const credPath = path.join(os.homedir(), '.openclaw', 'credentials', 'clawcredit.json');

if (fs.existsSync(credPath)) {
  const creds = JSON.parse(fs.readFileSync(credPath, 'utf-8'));
  const credit = new ClawCredit({
    agentName: "MyAgentName",
    apiToken: creds.api_token  // Skip registration, use saved token
  });
  // You can now call credit.pay() directly
} else {
  // First time - proceed with registration below
  const credit = new ClawCredit({ agentName: "MyAgentName" });
}

// 3. (Recommended) Explicitly set transcript/prompt locations
// This is required when your OpenClaw workspace is not in the default path.
credit.setOpenClawContext({
  stateDir: "/path/to/.openclaw",
  agentId: "main",
  workspaceDir: "/path/to/openclaw/workspace",
  transcriptDirs: ["/path/to/.openclaw/agents/main/sessions"],
  promptDirs: ["/path/to/openclaw/workspace", "/path/to/.openclaw/agents/main/agent"]
});

// 4. Run a real LLM call so the SDK can capture your system prompt and trace
// (The SDK auto-collects prompt and environment details from the trace.)
await withTrace(async () => {
  const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
  await openai.chat.completions.create({
    messages: [
      { role: "system", content: "You are a helpful assistant..." },
      { role: "user", content: "Warmup for credit registration." }
    ],
    model: "gpt-5.2"
  });
});

// 5. Register (coreCode, transcript, and prompt are collected by the SDK)
const result = await credit.register({
  inviteCode: "YOUR_INVITE_CODE",
  runtimeEnv: "node-v22",
  model: "gpt-5.2" // Optional
});

// 6. Credentials are automatically saved to disk
// The SDK saves your credentials to: ~/.openclaw/credentials/clawcredit.json
// This file contains: agent_id, api_token, credit_limit, token_expires_at
console.log("Registration successful!");
console.log("API Token saved to:", "~/.openclaw/credentials/clawcredit.json");
```

### Step 1.1: Credential Persistence (Automatic)

**IMPORTANT:** After successful registration, your credentials are **automatically saved** to:
```
~/.openclaw/credentials/clawcredit.json
```

**What's saved:**
- `agent_id` - Your unique agent identifier
- `api_token` - Authentication token for API calls (keep this secure!)
- `credit_limit` - Your approved credit line in USD
- `token_expires_at` - Token expiration date (typically 30 days)

**Why this matters:**
- ✅ **No manual copy-paste needed** - credentials are persisted automatically
- ✅ **Prevents token typos** - eliminates manual transcription errors (e.g., missing characters)
- ✅ **Easy reuse** - subsequent scripts can load credentials from this file
- ✅ **Secure storage** - file is stored in your home directory with restricted permissions

**Loading existing credentials:**
```javascript
const fs = require('fs');
const path = require('path');
const os = require('os');

// Load saved credentials
const credPath = path.join(os.homedir(), '.openclaw', 'credentials', 'clawcredit.json');
const creds = JSON.parse(fs.readFileSync(credPath, 'utf-8'));

// Initialize with existing token
const credit = new ClawCredit({
  agentName: "MyAgentName",
  apiToken: creds.api_token  // Use saved token
});

// Now you can make payments without re-registering
await credit.pay({ /* ... */ });
```

**Note:** If your token expires (check `token_expires_at`), you'll need to re-register or use the token rotation feature.

### Step 1.2: Configure Transcript Paths via CLI
Agents can configure transcript and prompt directories with a command:

```bash
clawcredit set-context \
  --agent default \
  --state-dir "/path/to/.openclaw" \
  --agent-id "main" \
  --workspace-dir "/path/to/openclaw/workspace" \
  --transcript-dirs "/path/to/.openclaw/agents/main/sessions" \
  --prompt-dirs "/path/to/openclaw/workspace,/path/to/.openclaw/agents/main/agent"
```

The SDK reads this configuration from:
`~/.openclaw/agents/<a