API Reference

Complete reference for the Clawd402 SDK and REST API.

SDK Reference

Client initialization

import { Clawd402Client } from '@clawd402/sdk'

const client = new Clawd402Client(config)

Parameters

Parameter	Type	Required	Description
`network`	`string`	Yes	Network identifier: `x402-mainnet`, `x402-testnet`
`wallet`	`WalletConfig`	Yes	Wallet configuration object
`policies`	`string \| PolicyConfig`	No	Path to policies file or policy object
`rpcUrl`	`string`	No	Custom RPC endpoint (overrides default)
`apiKey`	`string`	No	API key for managed service

Wallet configuration

// Private key
wallet: {
  type: 'private_key',
  key: process.env.PRIVATE_KEY
}

// HD wallet
wallet: {
  type: 'hd_wallet',
  mnemonic: process.env.MNEMONIC,
  derivationPath: "m/44'/60'/0'/0/0"
}

// Hardware wallet
wallet: {
  type: 'hardware',
  device: 'ledger',
  derivationPath: "m/44'/60'/0'/0/0"
}

Transaction execution

execute()

Submit a transaction for execution.

const result = await client.execute(params)

Parameters

{
  // Natural language instruction
  instruction?: string

  // OR structured intent
  action?: 'transfer' | 'swap' | 'approve' | 'call'
  asset?: string
  amount?: string
  recipient?: string
  contract?: string
  method?: string
  params?: any[]

  // Optional execution parameters
  urgency?: 'instant' | 'fast' | 'standard' | 'economy'
  maxGasPrice?: string
  maxPriorityFee?: string
  nonce?: number
  simulate?: boolean
}

Returns

{
  txHash: string
  nonce: number
  gasEstimate: string
  maxFeePerGas: string
  maxPriorityFeePerGas: string
  estimatedConfirmation: string  // ISO 8601 timestamp
  simulationResult?: {
    success: boolean
    gasUsed: string
    returnData: string
  }
}

Example

const result = await client.execute({
  instruction: "Transfer 50 USDC to 0xabcd...ef01",
  urgency: "fast"
})

waitForConfirmation()

Wait for transaction to reach specified confirmation depth.

const status = await client.waitForConfirmation(txHash, options)

Parameters

Parameter	Type	Default	Description
`txHash`	`string`	Required	Transaction hash
`confirmations`	`number`	3	Required confirmation depth
`timeout`	`number`	120000	Timeout in milliseconds
`pollInterval`	`number`	2000	Status check interval

Returns

{
  state: 'confirmed' | 'failed'
  blockNumber: number
  blockHash: string
  gasUsed: string
  effectiveGasPrice: string
  confirmations: number
  timestamp: string
  error?: string
}

getStatus()

Query current transaction status.

const status = await client.getStatus(txHash)

Returns

{
  state: 'pending' | 'included' | 'confirmed' | 'failed'
  blockNumber?: number
  blockHash?: string
  confirmations: number
  gasUsed?: string
  effectiveGasPrice?: string
  timestamp?: string
  error?: string
}

cancelTransaction()

Attempt to cancel pending transaction by submitting replacement with higher gas.

const cancellation = await client.cancelTransaction(txHash, options)

Parameters

{
  gasPrice?: string  // Custom gas price for cancellation
  maxAttempts?: number  // Maximum replacement attempts (default: 3)
}

Returns

{
  cancelled: boolean
  cancellationTxHash?: string
  error?: string
}

Balance and state queries

getBalance()

Query asset balance for wallet.

const balance = await client.getBalance(asset)

Parameters

Parameter	Type	Default	Description
`asset`	`string`	'ETH'	Asset symbol or contract address

Returns

{
  value: string  // Wei or token atomic units
  formatted: string  // Human-readable with decimals
  decimals: number
  symbol: string
  usdValue?: number
}

getNonce()

Get current nonce for wallet.

const nonce = await client.getNonce()

Returns

number

getGasPrice()

Get current gas price estimate.

const gasPrice = await client.getGasPrice(urgency)

Parameters

Parameter	Type	Default	Description
`urgency`	`string`	'standard'	Priority tier: instant, fast, standard, economy

Returns

{
  maxFeePerGas: string
  maxPriorityFeePerGas: string
  baseFee: string
  estimatedConfirmationTime: number  // seconds
}

Policy management

updatePolicies()

Update approval policies at runtime.

await client.updatePolicies(policies)

Parameters

Parameter	Type	Description
`policies`	`string \| PolicyConfig`	Path to policy file or policy object

getPendingApprovals()

Query transactions awaiting human approval.

const pending = await client.getPendingApprovals()

Returns

Array<{
  id: string
  txHash: string
  transaction: {
    from: string
    to: string
    value: string
    data: string
    type: string
  }
  matchedPolicy: string
  createdAt: string
  expiresAt: string
  valueUsd: number
}>

approveTransaction()

Approve pending transaction.

await client.approveTransaction(approvalId)

rejectTransaction()

Reject pending transaction.

await client.rejectTransaction(approvalId, reason)

Simulation and validation

simulate()

Simulate transaction execution without submitting.

const simulation = await client.simulate(params)

Parameters

Same as execute() method.

Returns

{
  success: boolean
  gasUsed: string
  returnData: string
  logs: Array<{
    address: string
    topics: string[]
    data: string
  }>
  error?: {
    reason: string
    code: string
  }
}

validateIntent()

Validate intent structure without execution.

const validation = await client.validateIntent(intent)

Returns

{
  valid: boolean
  parsed: {
    action: string
    params: object
  }
  errors?: string[]
  warnings?: string[]
}

REST API Reference

Base URL: https://api.clawd402.dev/v1

Authentication

Include API key in request header:

Authorization: Bearer YOUR_API_KEY

Endpoints

POST /transactions

Submit transaction for execution.

Request

{
  "instruction": "Transfer 50 USDC to 0xabcd...ef01",
  "urgency": "fast",
  "simulate": true
}

Response

{
  "txHash": "0x1234...",
  "nonce": 42,
  "gasEstimate": "21000",
  "maxFeePerGas": "50000000000",
  "estimatedConfirmation": "2026-03-17T18:05:30Z",
  "simulationResult": {
    "success": true,
    "gasUsed": "21000"
  }
}

GET /transactions/:txHash

Query transaction status.

Response

{
  "state": "confirmed",
  "blockNumber": 12345678,
  "confirmations": 5,
  "gasUsed": "21000",
  "effectiveGasPrice": "45000000000",
  "timestamp": "2026-03-17T18:05:30Z"
}

GET /balance/:asset

Query balance for authenticated wallet.

Response

{
  "value": "1000000000000000000",
  "formatted": "1.0",
  "decimals": 18,
  "symbol": "ETH",
  "usdValue": 3500.00
}

GET /gas-price

Get current gas price estimates.

Query parameters

Parameter	Type	Description
`urgency`	string	Priority tier: instant, fast, standard, economy

Response

{
  "maxFeePerGas": "50000000000",
  "maxPriorityFeePerGas": "2000000000",
  "baseFee": "48000000000",
  "estimatedConfirmationTime": 15
}

POST /simulate

Simulate transaction without submitting.

Request

{
  "instruction": "Swap 100 USDC for WETH",
  "simulate": true
}

Response

{
  "success": true,
  "gasUsed": "125000",
  "returnData": "0x...",
  "logs": [...]
}

Error codes

SDK errors

Code	Description
`INVALID_INTENT`	Intent parsing failed
`INSUFFICIENT_FUNDS`	Wallet balance too low
`SIMULATION_FAILED`	Pre-flight simulation detected failure
`GAS_PRICE_TOO_HIGH`	Gas price exceeds policy limit
`POLICY_REJECTED`	Transaction blocked by approval policy
`NONCE_CONFLICT`	Nonce already used or out of sequence
`TIMEOUT`	Operation exceeded timeout limit

API errors

Status	Code	Description
400	`invalid_request`	Request validation failed
401	`unauthorized`	Invalid or missing API key
402	`insufficient_funds`	Wallet balance too low
403	`policy_rejected`	Transaction blocked by policy
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error
503	`service_unavailable`	Temporary service disruption

Error response format

{
  "error": {
    "code": "insufficient_funds",
    "message": "Wallet balance (0.5 ETH) insufficient for transaction value (1.0 ETH) plus gas (0.001 ETH)",
    "details": {
      "required": "1.001",
      "available": "0.5",
      "currency": "ETH"
    }
  }
}

Rate limits

Free tier

100 requests per minute
10,000 requests per month

Paid tiers

Starter: 1,000 requests per minute
Professional: 10,000 requests per minute
Enterprise: Custom limits

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1710700000

Webhooks

Configure webhooks to receive real-time notifications.

Events

Event	Description
`transaction.submitted`	Transaction submitted to network
`transaction.confirmed`	Transaction reached confirmation depth
`transaction.failed`	Transaction failed or reverted
`approval.required`	Human approval needed
`approval.timeout`	Approval request expired

Webhook payload

{
  "event": "transaction.confirmed",
  "timestamp": "2026-03-17T18:05:30Z",
  "data": {
    "txHash": "0x1234...",
    "blockNumber": 12345678,
    "confirmations": 3,
    "gasUsed": "21000"
  }
}

Signature verification

Verify webhook signatures to ensure authenticity:

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

SDKs and libraries

TypeScript/JavaScript: @clawd402/sdk
Python: clawd402-python
Go: github.com/clawd402-base/clawd402-go
Rust: clawd402-rs

Support

API status: status.clawd402.dev
Changelog: docs.clawd402.dev/changelog
GitHub: github.com/clawd402-base/sdk
Support email: contact@clawd402.dev

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

API Reference

SDK Reference

Client initialization

Transaction execution

execute()

waitForConfirmation()

getStatus()

cancelTransaction()

Balance and state queries

getBalance()

getNonce()

getGasPrice()

Policy management

updatePolicies()

getPendingApprovals()

approveTransaction()

rejectTransaction()

Simulation and validation

simulate()

validateIntent()

REST API Reference

Authentication

Endpoints

POST /transactions

GET /transactions/:txHash

GET /balance/:asset

GET /gas-price

POST /simulate

Error codes

SDK errors

API errors

Rate limits

Free tier

Paid tiers

Webhooks

Events

Webhook payload

Signature verification

SDKs and libraries

Support