MCP Tools

Complete reference for all ClawFirst MCP tools with JSON schemas, parameters, and response formats.

Tool Overview

ClawFirst provides 6 core MCP tools for AI agent payment workflows:

Tool

x402.initialize_payment

Initialize a new payment session for an autonomous agent transaction.

Input Schema

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "description": "Payment amount with unit (e.g., '0.1 SOL', '250 USDC')",
      "pattern": "^\\d+(\\.\\d+)?\\s+(SOL|USDC|BONK)$"
    },
    "recipient": {
      "type": "string",
      "description": "Recipient wallet address or email identifier",
      "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$|^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    },
    "purpose": {
      "type": "string",
      "description": "Human-readable payment description",
      "maxLength": 500
    },
    "settlement_constraint": {
      "type": "string",
      "enum": ["immediate", "defer_until_approval", "scheduled"],
      "default": "immediate",
      "description": "Settlement timing constraint"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Unique key for idempotent retries",
      "maxLength": 256
    },
    "metadata": {
      "type": "object",
      "description": "Additional context for agent audit trail",
      "additionalProperties": true
    }
  },
  "required": ["amount", "recipient"]
}

Example Request

{
  "name": "x402.initialize_payment",
  "arguments": {
    "amount": "0.1 SOL",
    "recipient": "[email protected]",
    "purpose": "Invoice #4291 payment for cloud services",
    "settlement_constraint": "immediate",
    "idempotency_key": "invoice_4291_2026_03_01",
    "metadata": {
      "invoice_id": "INV-4291",
      "vendor": "Acme Corp",
      "agent_id": "invoice_settler_v2"
    }
  }
}

Response

{
  "success": true,
  "result": {
    "session_id": "sess_x4k9j2n8p5",
    "payment_address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
    "amount_lamports": 100000000,
    "recipient": "[email protected]",
    "expires_at": "2026-03-01T18:30:00Z",
    "status": "pending_authorization",
    "estimated_fees_lamports": 5000
  },
  "timestamp": 1709315400000,
  "rate_limit": {
    "limit": 100,
    "remaining": 87,
    "reset_at": 1709315460
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Agent wallet balance insufficient for transaction",
    "details": {
      "required": "0.1005 SOL",
      "available": "0.05 SOL",
      "shortfall": "0.0505 SOL"
    }
  },
  "timestamp": 1709315400000
}

x402.authorize_transaction

Sign and submit a blockchain transaction for an initialized payment session.

Input Schema

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Payment session ID from initialize_payment",
      "pattern": "^sess_[a-zA-Z0-9]+$"
    },
    "approval_token": {
      "type": "string",
      "enum": ["auto", "manual"],
      "default": "auto",
      "description": "Approval mechanism (auto uses approval policies)"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Unique key for idempotent retries",
      "maxLength": 256
    }
  },
  "required": ["session_id"]
}

Example Request

{
  "name": "x402.authorize_transaction",
  "arguments": {
    "session_id": "sess_x4k9j2n8p5",
    "approval_token": "auto",
    "idempotency_key": "authorize_invoice_4291"
  }
}

Response

{
  "success": true,
  "result": {
    "tx_signature": "3k9mN7PqRtV8sW2xY1zC4aB6nH5jL8fG9eD3cF2qA7sBpX5vW9rY3tZ8jM6nL4hK2fD",
    "status": "submitted",
    "session_id": "sess_x4k9j2n8p5",
    "submitted_at": "2026-03-01T17:45:23Z",
    "estimated_confirmation": "2-5 seconds",
    "block_height": null
  },
  "timestamp": 1709315523000,
  "rate_limit": {
    "limit": 100,
    "remaining": 86,
    "reset_at": 1709315460
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "APPROVAL_REQUIRED",
    "message": "Transaction exceeds auto-approval threshold",
    "details": {
      "amount": "0.1 SOL",
      "threshold": "0.01 SOL",
      "required_action": "human_approval",
      "approval_url": "https://clawfirst.xyz/approvals/sess_x4k9j2n8p5"
    }
  },
  "timestamp": 1709315523000
}

x402.verify_settlement

Verify transaction settlement and blockchain finality status.

Input Schema

{
  "type": "object",
  "properties": {
    "tx_signature": {
      "type": "string",
      "description": "Solana transaction signature",
      "pattern": "^[1-9A-HJ-NP-Za-km-z]{87,88}$"
    },
    "min_confirmations": {
      "type": "number",
      "description": "Minimum confirmations required",
      "default": 32,
      "minimum": 1,
      "maximum": 32
    }
  },
  "required": ["tx_signature"]
}

Example Request

{
  "name": "x402.verify_settlement",
  "arguments": {
    "tx_signature": "3k9mN7PqRtV8sW2xY1zC4aB6nH5jL8fG9eD3cF2qA7sBpX5vW9rY3tZ8jM6nL4hK2fD",
    "min_confirmations": 32
  }
}

Response

{
  "success": true,
  "result": {
    "tx_signature": "3k9mN7PqRtV8sW2xY1zC4aB6nH5jL8fG9eD3cF2qA7sBpX5vW9rY3tZ8jM6nL4hK2fD",
    "confirmations": 32,
    "settlement_state": "finalized",
    "block_height": 234567890,
    "block_time": "2026-03-01T17:45:28Z",
    "fee_lamports": 5000,
    "compute_units_consumed": 45000
  },
  "timestamp": 1709315528000,
  "rate_limit": {
    "limit": 100,
    "remaining": 85,
    "reset_at": 1709315460
  }
}

Settlement States

State

Description

pending

Transaction submitted, awaiting confirmation

confirmed

Confirmed but not yet finalized (< 32 confirmations)

finalized

Finalized with full security (≥ 32 confirmations)

failed

Transaction failed on-chain

x402.query_balance

Query agent wallet SOL and SPL token balances.

Input Schema

{
  "type": "object",
  "properties": {
    "wallet": {
      "type": "string",
      "description": "Wallet address (defaults to agent wallet if not provided)",
      "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
    },
    "include_tokens": {
      "type": "boolean",
      "description": "Include SPL token balances",
      "default": true
    }
  },
  "required": []
}

Example Request

{
  "name": "x402.query_balance",
  "arguments": {
    "include_tokens": true
  }
}

Response

{
  "success": true,
  "result": {
    "wallet": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
    "sol_balance": 1.25,
    "sol_balance_lamports": 1250000000,
    "tokens": [
      {
        "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "symbol": "USDC",
        "balance": 500.00,
        "decimals": 6
      },
      {
        "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
        "symbol": "BONK",
        "balance": 1000000.00,
        "decimals": 5
      }
    ],
    "last_updated": "2026-03-01T17:45:30Z"
  },
  "timestamp": 1709315530000,
  "rate_limit": {
    "limit": 100,
    "remaining": 84,
    "reset_at": 1709315460
  }
}

x402.estimate_fees

Estimate transaction fees for a potential payment.

Input Schema

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "description": "Payment amount with unit",
      "pattern": "^\\d+(\\.\\d+)?\\s+(SOL|USDC|BONK)$"
    },
    "recipient": {
      "type": "string",
      "description": "Recipient wallet address",
      "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
    },
    "priority_level": {
      "type": "string",
      "enum": ["low", "medium", "high", "very_high"],
      "default": "medium",
      "description": "Transaction priority level"
    }
  },
  "required": ["amount", "recipient"]
}

Example Request

{
  "name": "x402.estimate_fees",
  "arguments": {
    "amount": "0.1 SOL",
    "recipient": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "priority_level": "medium"
  }
}

Response

{
  "success": true,
  "result": {
    "base_fee_lamports": 5000,
    "priority_fee_lamports": 2000,
    "total_fees_lamports": 7000,
    "total_fees_sol": 0.000007,
    "estimated_compute_units": 50000,
    "priority_level": "medium",
    "estimated_confirmation_time": "2-5 seconds"
  },
  "timestamp": 1709315535000,
  "rate_limit": {
    "limit": 100,
    "remaining": 83,
    "reset_at": 1709315460
  }
}

x402.cancel_payment

Cancel a pending payment session before transaction authorization.

Input Schema

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Payment session ID to cancel",
      "pattern": "^sess_[a-zA-Z0-9]+$"
    },
    "reason": {
      "type": "string",
      "description": "Cancellation reason for audit trail",
      "maxLength": 500
    }
  },
  "required": ["session_id"]
}

Example Request

{
  "name": "x402.cancel_payment",
  "arguments": {
    "session_id": "sess_x4k9j2n8p5",
    "reason": "Recipient address validation failed"
  }
}

Response

{
  "success": true,
  "result": {
    "session_id": "sess_x4k9j2n8p5",
    "status": "cancelled",
    "cancelled_at": "2026-03-01T17:45:40Z",
    "reason": "Recipient address validation failed"
  },
  "timestamp": 1709315540000,
  "rate_limit": {
    "limit": 100,
    "remaining": 82,
    "reset_at": 1709315460
  }
}

Error Codes Reference

Code

Description

Retry?

INSUFFICIENT_BALANCE

Agent wallet lacks funds

No - Fund wallet

APPROVAL_REQUIRED

Exceeds auto-approval threshold

No - Request approval

RATE_LIMIT_EXCEEDED

Too many tool calls

Yes - Exponential backoff

INVALID_SESSION

Session expired or not found

No - Create new session

INVALID_RECIPIENT

Malformed wallet address

No - Fix address

SESSION_EXPIRED

Payment session timed out

No - Re-initialize

TRANSACTION_FAILED

On-chain transaction failed

Maybe - Check error details

NETWORK_ERROR

Solana RPC unavailable

Yes - Retry with backoff

Best Practices

1. Idempotency Keys

Always use idempotency keys for payment operations:

# Good - Idempotent
session = await provider.initialize_payment(
    amount="0.05 SOL",
    recipient="[email protected]",
    idempotency_key=f"invoice_{invoice.id}"
)

# Bad - Not idempotent
session = await provider.initialize_payment(
    amount="0.05 SOL",
    recipient="[email protected]"
)

2. Error Handling

Implement retry logic with exponential backoff:

for attempt in range(max_retries):
    try:
        result = await provider.authorize_transaction(session_id)
        break
    except RateLimitError as e:
        await asyncio.sleep(e.retry_after or (2 ** attempt))
    except ApprovalRequiredError:
        # Don't retry - requires human intervention
        raise

3. Settlement Verification

Always verify settlement before considering payment complete:

# Wait for finality
while True:
    settlement = await provider.verify_settlement(tx_signature)
    if settlement.confirmations >= 32:
        break
    await asyncio.sleep(2)

4. Pre-flight Checks

Query balance and estimate fees before authorizing:

# Check balance
balance = await provider.query_balance()
if balance.sol_balance < required_amount:
    raise InsufficientBalanceError()

# Estimate fees
fees = await provider.estimate_fees(amount, recipient)
total_required = amount + fees.total_fees_sol

if balance.sol_balance < total_required:
    raise InsufficientBalanceError()

# Proceed with payment
session = await provider.initialize_payment(...)

Next Steps

See OpenClaw examples for integration patterns
Review Authentication for security architecture
Check Rate Limits for throughput planning

PreviousTransaction Streams NextOverview

Last updated 23 hours ago

Good afternoon

hashtagTool Overview

hashtagx402.initialize_payment

hashtagInput Schema

hashtagExample Request

hashtagResponse

hashtagError Responses

hashtagx402.authorize_transaction

hashtagInput Schema

hashtagExample Request

hashtagResponse

hashtagError Responses

hashtagx402.verify_settlement

hashtagInput Schema

hashtagExample Request

hashtagResponse

hashtagSettlement States

hashtagx402.query_balance

hashtagInput Schema

hashtagExample Request

hashtagResponse

hashtagx402.estimate_fees

hashtagInput Schema

hashtagExample Request

hashtagResponse

hashtagx402.cancel_payment

hashtagInput Schema

hashtagExample Request

hashtagResponse

hashtagError Codes Reference

hashtagBest Practices

hashtag1. Idempotency Keys

hashtag2. Error Handling

hashtag3. Settlement Verification

hashtag4. Pre-flight Checks

hashtagNext Steps

Tool Overview

x402.initialize_payment

Input Schema

Example Request

Response

Error Responses

x402.authorize_transaction

Input Schema

Example Request

Response

Error Responses

x402.verify_settlement

Input Schema

Example Request

Response

Settlement States

x402.query_balance

Input Schema

Example Request

Response

x402.estimate_fees

Input Schema

Example Request

Response

x402.cancel_payment

Input Schema

Example Request

Response

Error Codes Reference

Best Practices

1. Idempotency Keys

2. Error Handling

3. Settlement Verification

4. Pre-flight Checks

Next Steps