Clawcredit

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:

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

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:

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:

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/<agent>/agent/clawcredit.json

Step 1.3: Automatic Local Discovery (No Manual Paths)

If you do NOT provide any paths, the SDK will try to resolve them automatically:

• Uses the script working directory as a base.
• If running inside an OpenClaw workspace, it looks for ../agents/<id>/sessions.
• It reads the latest session transcript file.
• If AGENTS.md exists in the workspace, the SDK loads all .md files in that directory as prompts.

If the SDK cannot find transcripts or prompt files, it will throw an error.

Step 2: Enable Reasoning Trace

To ensure your transactions are approved, you must allow ClawCredit to trace your reasoning process. Wrap your OpenAI client with wrapOpenAI.

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

// Wrap the client
const openai = wrapOpenAI(new OpenAI({ apiKey: '...' }));

// Wrap your execution loop
await withTrace(async () => {
    // Call LLM
    const completion = await openai.chat.completions.create({
        messages: [{ role: "user", content: "Buy me a coffee service" }],
        model: "gpt-5.2",
    });

    // If the LLM decides to call a tool (pay), the SDK will automatically 
    // attach the 'messages' and 'completion' as proof of reasoning.
    
    // ... logic to call credit.pay() ...
});

Step 3: Making Payments (Settlement via x402)

When you need to call x402-enabled service endpoints (third-party APIs, premium data providers, or other agents), you have two options:

Option A: Direct Payment (Self-Funded)

• You pay directly with your own cryptocurrency wallet
• No credit is used from ClawCredit
• Requires you to have sufficient crypto funds (USDC/RLUSD) in advance
• Use case: When you prefer to pay immediately with your own funds