@x402-tools/sdk

@x402-tools/sdk

Define a pay-per-call x402 service with a single handler. The x402tools platform takes your define() export, injects the x402 paywall, input validation, timeout enforcement, telemetry, and discovery (/.well-known/x402, /openapi.json, /health), then hosts it and settles USDC to your wallet.

Status: Slice 0 of the platform build (PRD §4.1 / §4.4). The author-facing define() API and the runtime wrapper are implemented and tested. The CLI, control-plane API, and managed deploy land in later slices.

Install

npm install @x402-tools/sdk

Define a service

import { define } from "@x402-tools/sdk";

export default define({
  name: "sentiment-analysis",            // kebab-case, globally unique
  description: "Analyze text sentiment (-1 to 1).",
  price: "$0.002",                        // USDC per call
  input: {
    text: { type: "string", required: true, maxLength: 5000 },
  },
  output: { type: "json" },
  async handler(input, ctx) {
    ctx.logger.info("scoring", { len: input.text.length });
    return { score: score(input.text) };
  },
});

handler(input, ctx) receives validated input (defaults applied) and a Context with fetch, env, logger, requestId, callerAddress, and a cache. Return a JSON-serializable value, a Buffer, or { body, contentType } for binary responses.

Run it locally

For local iteration, run your handler with the built-in dev server — no paywall, no payments, no platform dependencies (only express):

import { startDevServer } from "@x402-tools/sdk/dev";
import def from "./handler.js";

startDevServer(def, { port: 8787 }); // POST / with your input, /health, /openapi.json

This is what x402tools dev runs. On the platform, a generated wrapper calls the production runtime entry point instead:

import { serve } from "@x402-tools/sdk/runtime";
import def from "./handler.js";

serve(def);                 // paywall on, payTo from WALLET_ADDRESS

Subpath exports

• @x402-tools/sdk — author API (define, validateInput, types). Zero server deps.
• @x402-tools/sdk/dev — createDevServer() / startDevServer(). Express-only, no paywall. Safe for external developers to install and run.
• @x402-tools/sdk/runtime — serve() / createServiceApp(). Builds the paywalled Express app on top of @x402-tools/core; used platform-side only (its dependencies are injected by the platform build, never pulled by npm install). Emits a usage event per call to ${USAGE_COLLECTOR_URL}/v1/ingest/usage (with USAGE_INGEST_TOKEN) for platform analytics; no-op when those are unset.

Deploy to the platform

Install the CLI and ship your handler — the platform builds it, hosts it behind the x402 paywall, and settles USDC to your wallet:

npm install -g @x402-tools/cli
x402tools init                 # or drop this handler.ts into a project
npm install
x402tools login <github-token>
npm run deploy                 # build + deploy
x402tools payout 0xYourWallet  # where your 70% revenue share is paid
x402tools status               # URL, calls, revenue, trust score

See @x402-tools/cli for the full command reference.

Develop & test

npm run build
npm test            # unit/e2e tests for define + runtime
npm run test:consumer  # packs the SDK and installs it as an external dev would,
                       # proving /dev works without @x402-tools/core