Skip to main content

Quick Start

Get a paid API endpoint live in under 5 minutes.

Prerequisites​

  • Bankr CLI installed and authenticated (bankr login)

1. Initialize​

bankr x402 init

This creates:

  • x402/ directory for your service handlers
  • bankr.x402.json config file

2. Add a Service​

bankr x402 add weather

This scaffolds x402/weather/index.ts with a starter template.

3. Add Dependencies (optional)​

If your handler needs npm packages, add a package.json to your service directory:

cd x402/weather
bun add zod @langchain/openai   # or any npm packages you need

When you answer "yes" to "Will this service use npm packages?" during bankr x402 add, a package.json is scaffolded automatically.

4. Write Your Handler​

Edit x402/weather/index.ts. Your handler is a plain function that receives a Request and returns a Response:

export default async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);
  const city = url.searchParams.get("city") ?? "New York";

  // Your business logic here — call external APIs, process data, run models
  const weather = await getWeather(city);

  return Response.json({
    city,
    temperature: weather.temp,
    conditions: weather.conditions,
    timestamp: new Date().toISOString(),
  });
}

async function getWeather(city: string) {
  // Use process.env for your API keys (set via bankr x402 env set)
  const apiKey = process.env.WEATHER_API_KEY;
  const res = await fetch(
    `https://api.weather.example/v1/current?city=${city}&key=${apiKey}`,
  );
  return res.json();
}

That's it. No x402 imports, no payment middleware, no blockchain code. Bankr wraps the payment layer around your handler automatically.

5. Set Environment Variables (optional)​

If your handler uses API keys or secrets:

bankr x402 env set WEATHER_API_KEY=your-api-key-here

Environment variables are encrypted at rest and available as process.env in your handler. You can set them before or after deploying. See Security for details.

6. Define Your Schema​

The schema is how agents and humans know how to use your service. It describes your inputs and outputs using JSON Schema — what fields to send, what types they are, and what comes back.

Why this matters:

  • AI agents use the schema to call your endpoint correctly without any hardcoded integration
  • The Bankr CLI reads it for interactive mode (bankr x402 call -i), prompting users for each field
  • The marketplace displays it so people can understand your service at a glance

Add the schema field to your service in bankr.x402.json:

{
  "network": "base",
  "currency": "USDC",
  "services": {
    "weather": {
      "description": "Real-time weather data for any city",
      "price": "0.001",
      "methods": ["GET"],
      "schema": {
        "input": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name (e.g. 'London', 'New York')"
            },
            "units": {
              "type": "string",
              "description": "Temperature units",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["city"]
        },
        "output": {
          "type": "object",
          "properties": {
            "temperature": { "type": "number", "description": "Current temperature" },
            "conditions": { "type": "string", "description": "Weather conditions (e.g. 'sunny', 'cloudy')" },
            "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }
          }
        }
      }
    }
  }
}

Tips for good schemas:

  • Add description to every property — this is what agents and the interactive CLI show to users
  • Mark fields as required so callers know what's mandatory
  • Use enum for fields with a fixed set of values
  • For POST services, input properties map to JSON body fields. For GET services, they map to query parameters.

See Config File for the full schema reference including arrays, nested objects, and legacy formats.

7. Configure Pricing​

Set the price field in bankr.x402.json (already shown above), or use the interactive configurator:

bankr x402 configure weather

Prices are in USD, paid in USDC. The minimum is 0.000001. Consider your per-request costs (API calls, inference, compute) and add a margin.

8. Deploy​

bankr x402 deploy

Output:

✔ Deployed 1 service(s)

  Service:  weather
  URL:      https://x402.bankr.bot/0xYourWallet/weather
  Price:    $0.001 USDC/req
  Version:  1

Your endpoint is live. Agents can now discover and pay for it automatically.

9. Test It​

Inspect the schema​

Check what your endpoint expects before calling it:

bankr x402 schema https://x402.bankr.bot/0xYourWallet/weather

Call with the CLI​

The easiest way to test is with bankr x402 call:

# Direct call with query params
bankr x402 call https://x402.bankr.bot/0xYourWallet/weather?city=London

# Interactive mode — the CLI reads the schema and prompts for each field
bankr x402 call https://x402.bankr.bot/0xYourWallet/weather -i

Without payment (returns 402)​

curl -i https://x402.bankr.bot/0xYourWallet/weather?city=London

With payment (using x402-fetch)​

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";
import { wrapFetchWithPayment } from "x402-fetch";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const wallet = createWalletClient({ account, chain: base, transport: http() });
const paidFetch = wrapFetchWithPayment(fetch, wallet, BigInt(1_000_000));

const res = await paidFetch(
  "https://x402.bankr.bot/0xYourWallet/weather?city=London",
);
console.log(await res.json());
// { city: "London", temperature: 12, conditions: "cloudy", timestamp: "..." }

Next Steps​