FAQ

General Questions

What is Claw402?

Claw402 is an MCP-native integration layer that enables OpenClaw AI agents to execute autonomous transactions on the x402 protocol. We provide a secure, non-custodial architecture that translates natural language payment instructions into protocol-level blockchain transactions.

How do I get started?

1. Install the Claw402 provider: pip install claw402 or npm install @claw402/mcp-sdk

2. Configure your agent wallet (we never access your private keys)

3. Set up approval policies for autonomous transaction limits

4. Connect your AI agent to Claw402 MCP tools

For detailed integration guides, see our Getting Started guide.

What is x402?

x402 is a payment protocol that enables cryptocurrency payments over HTTP with cryptographic proof validation. It allows AI agents to programmatically initiate and verify blockchain transactions without requiring traditional wallet UI interactions.

Learn more at x402.org

What is MCP?

Model Context Protocol (MCP) is an open standard for AI agent tool integration. Claw402 implements MCP-native tools that allow agents to:

• Initialize payment sessions declaratively

• Authorize transactions with approval policies

• Verify settlement status in real-time

• Query wallet balances and estimate fees

Do I need blockchain knowledge to use Claw402?

No. Claw402 abstracts all blockchain complexity. Your AI agent describes payment intent in natural language (e.g., "Pay invoice #4291 for $250 USDC"), and Claw402 handles transaction construction, signing, and settlement verification.

Which blockchains does Claw402 support?

Claw402 currently supports Solana mainnet-beta and devnet. We handle all blockchain interactions through our MCP tool suite, so agents never interact with RPC nodes directly.

AI Agent Integration

What agent frameworks are compatible with Claw402?

Claw402 supports any MCP-capable agent framework:

• OpenClaw (Python) - Native provider integration

• Claude Code (TypeScript) - MCP server integration

• LangChain (Python/TypeScript) - Custom MCP client

• AutoGPT (Python) - MCP tool integration

• Custom agents - Standard MCP protocol

How does Claw402 ensure agent transactions are secure?

Claw402 implements a non-custodial security architecture:

• HSM isolation: Private keys never enter LLM context windows

• Approval policies: Multi-tier transaction limits with human-in-loop workflows

• Idempotency: Prevent duplicate transactions from retry logic

• Audit logging: Complete transaction history for compliance

See Authentication for architecture details.

Can agents make unlimited transactions?

No. Agents operate within approval policy constraints you configure:

policies:
  - auto_approve: up to 0.01 SOL
  - require_agent_confirmation: 0.01 - 0.1 SOL
  - human_approval_required: above 0.1 SOL

This ensures autonomous agents cannot exceed predefined transaction limits.

What happens if an agent tries to exceed its approval limit?

The MCP tool will return an error response indicating approval is required:

{
  "success": false,
  "error": {
    "code": "APPROVAL_REQUIRED",
    "message": "Transaction exceeds auto-approval threshold",
    "required_action": "human_approval"
  }
}

The transaction is blocked until a human operator provides approval.

MCP Tools

What MCP tools does Claw402 provide?

Claw402 provides 6 core MCP tools:

Tool	Purpose
x402.initialize_payment	Create payment session from agent intent
x402.authorize_transaction	Sign and submit blockchain transaction
x402.verify_settlement	Confirm transaction finality
x402.query_balance	Check wallet SOL/token balances
x402.estimate_fees	Calculate transaction costs
x402.cancel_payment	Abort pending payment session

How do agents call MCP tools?

OpenClaw Python:

from claw402 import X402Provider

provider = X402Provider(
    wallet_path="~/.config/solana/agent.json"
)

session = await provider.initialize_payment(
    amount="0.1 SOL",
    recipient="[email protected]"
)

MCP Protocol (TypeScript):

const result = await client.callTool({
  name: 'x402.initialize_payment',
  arguments: {
    amount: '0.1 SOL',
    recipient: '[email protected]'
  }
});

Are MCP tool calls idempotent?

Yes. All Claw402 MCP tools support idempotency keys:

session = await provider.initialize_payment(
    amount="0.05 SOL",
    recipient="[email protected]",
    idempotency_key="invoice_4291"  # Safe to retry
)

Retrying with the same key returns the existing session instead of creating a duplicate.

Wallet & Keys

How do agent wallets work?

Claw402 uses non-custodial agent wallets:

1. You generate a Solana keypair for your agent: solana-keygen new -o agent.json

2. Configure Claw402 to use this wallet for signing

3. Private keys remain in HSM-backed signing context, never exposed to the LLM

Where are private keys stored?

Private keys are stored in:

• Local filesystem (development): ~/.config/solana/agent.json

• Hardware Security Modules (production): AWS KMS, Google Cloud KMS, Azure Key Vault

• Environment variables (containerized): Injected at runtime, never in source code

Claw402 accesses keys for signing but never sends them to the LLM context window.

Do I need multiple wallets for multiple agents?

Yes, we recommend:

• One wallet per agent for transaction attribution

• Separate wallets for development vs. production

• Hot wallets (HSM) for active agents

• Cold wallets for treasury reserves

How do I fund an agent wallet?

# Devnet (free test SOL)
solana airdrop 1 ~/.config/solana/agent.json --url devnet

# Mainnet (transfer from your wallet)
solana transfer ~/.config/solana/agent.json 0.1 SOL \
  --from ~/.config/solana/main-wallet.json \
  --url mainnet-beta

Rate Limits & Performance

What are the rate limits for agent transactions?

Rate limits vary by plan:

• Developer: 10 transactions/min, 100 tool calls/min

• Production: 100 transactions/min, 1,000 tool calls/min

• Enterprise: Custom limits for high-volume agents

See Rate Limits for details.

What happens if an agent exceeds rate limits?

MCP tools return a RATE_LIMIT_EXCEEDED error with retry guidance:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "retry_after": 30
  }
}

Implement exponential backoff in your agent retry logic.

How fast are agent transactions?

• MCP tool latency: < 50ms (HSM signing)

• Transaction submission: ~200ms (Solana RPC)

• Settlement finality: 2-5 seconds (32 confirmations)

End-to-end payment completion: ~5 seconds from agent intent to finalized transaction.

Can I batch multiple agent payments?

Yes, for multiple payments to the same recipient, consolidate amounts:

# Bad: 10 separate sessions
for invoice in invoices:
    await provider.initialize_payment(invoice.amount, "[email protected]")

# Good: 1 aggregated session
total = sum(inv.amount for inv in invoices)
await provider.initialize_payment(total, "[email protected]")

Errors & Troubleshooting

Common agent transaction errors

Error Code	Cause	Solution
INSUFFICIENT_BALANCE	Agent wallet lacks SOL	Fund wallet with SOL for fees
APPROVAL_REQUIRED	Exceeds approval threshold	Lower amount or request human approval
RATE_LIMIT_EXCEEDED	Too many transactions	Implement backoff, upgrade plan
INVALID_RECIPIENT	Malformed wallet address	Validate recipient format

Why is my agent transaction failing?

Check these common issues:

1. Wallet balance: Ensure agent has sufficient SOL for transaction fees

2. Approval policy: Verify amount doesn't exceed auto-approval threshold

3. Idempotency key: Don't reuse keys for different payment intents

4. Network: Confirm Solana RPC is reachable (mainnet-beta vs devnet)

How do I debug agent MCP tool calls?

Enable debug logging:

# Python
import logging
logging.basicConfig(level=logging.DEBUG)

# View full MCP request/response
provider = X402Provider(wallet_path="...", debug=True)

// TypeScript
const client = new Client({
  name: 'agent',
  version: '1.0.0'
}, {
  capabilities: {},
  debug: true  // Log all tool calls
});

What should I do if settlement verification times out?

Settlement typically completes in 2-5 seconds. If verification times out:

1. Check Solana network status: status.solana.com

2. Verify transaction signature on Solana Explorer

3. Increase timeout threshold in agent code (default: 60s)

4. Contact support if issue persists

Security & Compliance

Are agent transactions auditable?

Yes. Claw402 provides complete audit logging:

• Agent identity: Which agent initiated the transaction

• Payment intent: Natural language instruction from agent

• Approval decision: Auto-approved vs. human-approved

• Transaction context: Amount, recipient, timestamp, signature

Export audit logs from the dashboard for compliance reporting.

How do I implement human-in-loop approval?

Configure approval policies with human approval thresholds:

policies:
  - name: large_payments
    min_amount: 1.0 SOL
    action: human_approval_required
    notification_webhook: https://your-app.com/approve

When agents attempt large transactions, you receive a webhook notification to approve/reject.

Can agents reverse transactions?

No. Blockchain transactions are irreversible once finalized. Implement these safeguards:

• Pre-flight validation: Agents query balance and estimate fees before authorizing

• Approval policies: Require confirmation for high-value transactions

• Idempotency keys: Prevent accidental duplicate payments

• Dry-run mode: Test agent logic on devnet first

How often should I rotate agent wallet keys?

Best practices for key rotation:

• Development wallets: Rotate every 90 days

• Production wallets: Rotate every 30 days or after security incidents

• High-value agents: Implement automated key rotation via HSM

Generate new wallet, update Claw402 configuration, and transfer remaining balance from old wallet.

Use Cases

What are common agent use cases for Claw402?

Production agent use cases include:

1. Invoice settlement: Autonomously pay vendor invoices based on PO validation

2. SaaS subscriptions: Renew API subscriptions before expiration

3. Resource allocation: Provision cloud compute and pay providers

4. Micropayments: Pay for API calls or data access on-demand

5. Treasury management: Coordinate multi-agent payment workflows

See Examples for implementation patterns.

Can agents manage multi-signature wallets?

Not currently. Claw402 supports single-signature agent wallets. For multi-sig requirements:

• Implement human approval workflows for high-value transactions

• Use separate agents with different approval thresholds

• Contact [email protected] for custom multi-sig support

How do I coordinate multiple agents?

For multi-agent systems:

# Separate wallets per agent
invoice_agent = Agent(providers=[X402Provider(
    wallet_path="~/.config/solana/invoice_agent.json",
    approval_policy="threshold:100_USDC"
)])

subscription_agent = Agent(providers=[X402Provider(
    wallet_path="~/.config/solana/subscription_agent.json",
    approval_policy="threshold:50_USDC"
)])

# Run concurrently
await asyncio.gather(
    invoice_agent.run("Process invoices"),
    subscription_agent.run("Renew subscriptions")
)

Support

How can I get help?

Support channels:

• Documentation: docs.claw402.xyz

• Status page: status.claw402.xyz

• Twitter: @claw402dotxyz

• Email: [email protected]

• Enterprise support: [email protected]

Is there a community for agent developers?

Join the Claw402 community:

• Twitter: @claw402dotxyz for updates

• GitHub: github.com/claw402 for examples

• Discord: discord.gg/claw402 (coming soon)

How do I report a bug?

Email [email protected] with:

• Agent framework (OpenClaw, LangChain, etc.)

• MCP tool call that failed

• Error message and code

• Transaction signature (if applicable)

• Logs with sensitive data redacted

We respond to bug reports within 24 hours (4 hours for Enterprise customers).

Best Practices

Should agents implement retry logic?

Yes. Implement exponential backoff for:

• Rate limit errors: Retry with increasing delay

• Network timeouts: Retry with idempotency key

• Settlement delays: Poll verify_settlement with exponential backoff

Never retry for:

• INSUFFICIENT_BALANCE: Fund wallet instead

• INVALID_RECIPIENT: Fix recipient address

• APPROVAL_REQUIRED: Request human approval

How should I test agent integrations?

Testing strategy:

1. Unit tests: Mock MCP tool responses

2. Devnet testing: Test with free devnet SOL

3. Canary deployment: Run one production agent with small limits

4. Gradual rollout: Increase approval thresholds incrementally

Never test directly on mainnet without devnet validation first.

What monitoring should I implement for production agents?

Production monitoring checklist:

• Transaction volume: Track daily transaction count per agent

• Failure rate: Alert on >5% transaction failure rate

• Wallet balance: Alert when balance drops below threshold

• Approval rejections: Monitor human approval rejection rate

• Settlement latency: Track p95/p99 settlement times

Integrate with monitoring tools: Datadog, New Relic, or custom dashboards via Claw402 WebSocket streams.

When should I use WebSockets instead of REST?

Use WebSocket transaction streams for:

• Real-time agent dashboards

• Reactive workflows triggered by settlement

• Multi-agent coordination based on transaction events

• Live transaction monitoring during testing

For standard agent workflows, MCP tool calls (REST equivalent) are sufficient.