Developer Docs

Put production-grade security in front of every autonomous trade.

WatchTower gives agents a simple execution gate: run the threat engine, evaluate policy, verify the signed permit, then execute only when Authorization passes.

SDK quickstart View source

Quickstart

Use the SDK when WatchTower sits inside your agent runtime. The default client already knows the trusted WatchTower signer and permit domain, so normal integrations do not need custom trust configuration.

npm install okx-watchtower-middleware
"text-purple-400">import { WatchTowerClient, WatchTowerPaymentRequiredError } "text-purple-400">from "okx-watchtower-middleware"; "text-purple-400">const wt = "text-purple-400">new WatchTowerClient({  apiUrl: "https://watchtowr.xyz",  agentWallet: "0xYourAgentWallet",}); "text-purple-400">try {  "text-purple-400">const authorization = "text-purple-400">await wt.authorize({    action: "swap",    token: "0xTokenAddress",  });   "text-purple-400">if (!authorization.executable) {    "text-purple-400">throw "text-purple-400">new Error(`Execution blocked: ${authorization.decision}`);  }   "text-purple-400">await executeTrade();} "text-purple-400">catch (error) {  "text-purple-400">if (error instanceof WatchTowerPaymentRequiredError) {    "text-cyan-400">console.log(error.paymentRequired);  }}

For production agents, add the payment configuration below or retry with a wallet-provided payment signature. For a local demo, run the app, use /network to generate a free token report, or open /verify to inspect a confirmed registry transaction.

SDK Integration

authorize() is the premium Permission to Execute flow. It runs full threat intelligence, evaluates policy, and only returns executable: true after the signed permit verifies locally.

"text-purple-400">import { WatchTowerClient, WatchTowerAuthorizationError } "text-purple-400">from "okx-watchtower-middleware"; "text-purple-400">const wt = "text-purple-400">new WatchTowerClient({  apiUrl: "https://watchtowr.xyz",  agentWallet: "0xYourAgentWallet",  threshold: 70,  paymentPrivateKey: "text-cyan-400">process.env.AGENT_PAYMENT_KEY,  paymentPolicy: {    apiOrigin: "https://watchtowr.xyz",    // Payment network, not the token scan chain.    chainId: 196,    tokenAddress: "text-cyan-400">process.env.MAINNET_USDT_ADDRESS!,    tokenDecimals: 6,    treasuryAddress: "text-cyan-400">process.env.MAINNET_TREASURY_ADDRESS!,    maxAmount: "1",  },}); "text-purple-400">try {  "text-purple-400">const authorization = "text-purple-400">await wt.authorize({    action: "swap",    token: "0xTokenAddress",    amountUsd: 250,  });   "text-purple-400">if (!authorization.executable) {    "text-cyan-400">console.log("Trade blocked", authorization.decision);    "text-cyan-400">return;  }   "text-purple-400">await executeTrade();} "text-purple-400">catch (error) {  "text-purple-400">if (error instanceof WatchTowerAuthorizationError) {    "text-cyan-400">console.log("Permit verification failed", error.message);  }}

Configure paymentPrivateKey only inside a secure agent runtime. Automatic x402 signing also requires a paymentPolicy that pins the API origin, chain, token, treasury, and maximum amount. Without a key, the SDK returns the payment challenge so your wallet flow can sign it.

MCP Tools

MCP lets local AI agents discover WatchTower as a protected tool provider. The endpoint is Streamable HTTP and uses the same payment, validation, chain-resolution, and Authorization logic as REST.

{  "mcpServers": {    "watchtower": {      "url": "https://watchtowr.xyz/api/mcp"    }  }}

Tools: scan_token for Firewall, authorize_transaction for Authorization, and deep_scan_token as a compatibility alias for existing Marketplace integrations.

REST API

REST is useful when you do not want the SDK package. Inputs are validated before payment, so malformed requests do not consume a valid settlement.

POST /api/scan       // Firewall, 0.5 USDTPOST /api/authorize   // Authorization, 1 USDTPOST /api/scan/deep   // compatibility alias {  "tokenAddress": "0x...",  "agentWallet": "0x...",  "action": "swap"}

chainId is optional and refers to the token scan chain, not the x402 payment network. Omit it for auto-detection; provide it only when you already know the token deployment chain.

Payments

WatchTower uses x402 with the OKX facilitator for machine payments. Protected endpoints return 402 Payment Required with a PAYMENT-REQUIRED challenge.

PAYMENT-SIGNATURE: <base64-encoded PaymentPayload>

The SDK can reuse the signed payment payload during retries. WatchTower records confirmed facilitator settlements before service delivery, and failed service delivery releases the payment back into a recoverable state.

Reports and Attestations

Execution Authorization generates public reports at /report/[reportHash]. The response also exposes the threat-analysis hash, the permit hash when a permit is issued, and an attestation status so developers can tell each artifact apart.

analysisHash // threat-analysis content hash, legacy scanHash aliaspermitHash   // signed Execution Permit hash, only when a permit is issuedreportHash   // public /report/[reportHash] lookup keyattestation.status // pending | confirmed | failed

Authorization is returned as soon as the Execution Permit verifies locally. X Layer anchoring runs as audit work, and /verify can decode a confirmed registry transaction when one is available.

Back to SDK section Read README on GitHub