x500-sdk

Parametric micro-insurance for AI agent API payments on Hedera testnet.

x500-sdk wraps fetch so agents can call merchant APIs through the x500 insured gateway: pay the merchant via x402 Exact (HBAR), pay a flat insurance premium from on-chain escrow, and receive parametric refunds when calls fail or breach SLA.

V1 scope: Hedera testnet only · native HBAR (0.0.0) · no USDC / HTS / mainnet.

Install

npm install x500-sdk

Requires Node.js 18+ (uses native fetch).

Quick start

import { createX500 } from "x500-sdk";

const x500 = createX500({
  network: "testnet",
  accountId: process.env.X500_AGENT_ACCOUNT_ID!,      // 0.0.x
  privateKey: process.env.HEDERA_AGENT_PRIVATE_KEY!, // ECDSA hex 0x...
});

// 1. Fund insurance escrow once (tinybars)
await x500.setup({ escrowTinybars: 50_000_000n }); // 0.5 HBAR

// 2. Call a registered merchant by origin URL — slug resolved automatically
const res = await x500.fetch(
  "https://your-merchant.example/paid/weather?city=Paris",
);

console.log(res.status, await res.text());
await x500.close();

The merchant origin must be registered in the x500 dashboard. You do not need to know the slug or proxy URL upfront.

How it works

Agent (SDK)  →  Market proxy (/v1/{slug}/…)  →  Merchant x402 API
                    ↓
              Classify outcome → settle premium / refund on Hedera

| Payment rail | What happens | |--------------|----------------| | Merchant API | x402 CRYPTOTRANSFER — agent pays merchant HBAR during the HTTP call | | Insurance | Premium debited from agent escrow → pool via settleBatch | | Refund | Parametric refund from pool → agent on covered failures / SLA breach |

The SDK adds x-x500-agent-account-id on insured requests and parses response headers (x-x500-call-id, x-x500-premium, x-x500-refund, x-x500-outcome).

Configuration

Required

| Variable / option | Description | |-------------------|-------------| | network | Must be "testnet" in V1 | | accountId | Hedera agent account 0.0.x | | privateKey | ECDSA private key (hex, 0x…) |

Optional overrides

Live testnet defaults are built in. Override via createX500({ … }) or environment variables:

| Option | Env var | Default | |--------|---------|---------| | proxyUrl | MARKET_PROXY_URL or PROXY_URL | https://xmarket-5341291432.us-central1.run.app | | indexerUrl | INDEXER_URL | https://xindexer-5341291432.us-central1.run.app | | facilitatorUrl | FACILITATOR_URL | https://xfacilitator-5341291432.us-central1.run.app | | poolContractId | X500_POOL_CONTRACT_ID | 0.0.9585433 |

For local development, point env vars at your own proxy/indexer/facilitator.

API reference

createX500(options) → X500Client

Factory for the agent client. Throws if network !== "testnet".

HTTP methods

| Method | Description | |--------|-------------| | fetch(url, init?) | Insured fetch — drop-in replacement for fetch. Merchant origin URLs are auto-resolved to the proxy; proxy paths (/v1/{slug}/…) and full proxy URLs pass through. Handles x402 402 → pay → retry. | | pay(url, init?) | x402-only payment path — no insurance wrap. Use for direct merchant calls outside the proxy. |

Merchant resolution

| Method | Description | |--------|-------------| | resolveMerchant(origin) | GET /api/endpoints/resolve — returns { slug, hostname, insuredUrl, apiPriceTinybars, flatPremiumTinybars }. |

Exported helpers (import from x500-sdk):

| Function | Description | |----------|-------------| | insuredUrlForMerchant(url, opts?) | Full merchant URL → insured proxy URL. | | normalizeMerchantOrigin(url) | Strip path → https://host. | | insuredProxyUrl(slug, path?, base?) | Build {proxy}/v1/{slug}/{path}. |

Escrow & balance

| Method | Description | |--------|-------------| | setup({ escrowTinybars? }) | depositEscrow on X500Pool. Default 30M tinybars (0.3 HBAR). | | topUp(tinybars) | Additional escrow deposit. | | getBalance() | Agent wallet HBAR balance in tinybars. |

Indexer reads

| Method | Description | |--------|-------------| | getCall(callId) | GET /api/calls/:id — settlement status, outcome, tx id. | | getAgent(accountId?) | GET /api/agents/:id — escrow stats and call history. |

Events

x500.on("billed", (e) => {
  console.log(`Premium ${e.premiumTinybars} tb — call ${e.callId}`);
});

x500.on("refund", (e) => {
  console.log(`Refund ${e.refundTinybars} tb — call ${e.callId}`);
});

x500.on("failure", (e) => {
  console.log(`Failed: ${e.outcome} HTTP ${e.status}`);
});

x500.on("degraded", (e) => {
  console.log(`Settlement pending — call ${e.callId}`);
});

Each handler returns an unsubscribe function. Event payload type: X500CallEvent.

Lifecycle

| Method | Description | |--------|-------------| | close() | Close the Hedera SDK client. Call when done. |

Response headers

When calling through the insured proxy, inspect:

| Header | Meaning | |--------|---------| | x-x500-call-id | Unique call id (maps to on-chain settlement) | | x-x500-outcome | ok, latency_breach, server_error, network_error, client_error, … | | x-x500-premium | Insurance premium charged (tinybars) | | x-x500-refund | Refund credited (tinybars), 0 if none | | x-x500-settlement-pending | 1 if on-chain settle not yet confirmed |

LangChain / agent frameworks

See the monorepo example: example/agent — Groq + get_insured_weather tool using fetch.

import { tool } from "@langchain/core/tools";
import { z } from "zod";

const weatherTool = tool(
  async ({ city }) => {
    const url = `${merchantOrigin}/paid/weather?city=${encodeURIComponent(city)}`;
    const res = await x500.fetch(url);
    return res.ok ? await res.text() : `error ${res.status}`;
  },
  {
    name: "get_insured_weather",
    schema: z.object({ city: z.string() }),
  },
);

Prerequisites

1. Hedera testnet account with HBAR (portal.hedera.com).
2. Insurance escrow — setup() or x500 approve CLI once.
3. Registered merchant — merchant registers their public origin URL in the x500 dashboard.

CLI

Prefer a terminal? Use the companion package x500:

npm install -g x500
x500 --network testnet balance
x500 --network testnet approve
x500 --network testnet https://merchant.example/paid/weather?city=Tokyo

Constants

import {
  HBAR_ASSET,              // "0.0.0"
  HEDERA_TESTNET,           // "hedera:testnet"
  DEFAULT_MARKET_PROXY_URL,
  DEFAULT_INDEXER_URL,
  DEFAULT_FACILITATOR_URL,
  DEFAULT_POOL_CONTRACT_ID,
} from "x500-sdk";

Links

• x500 monorepo & docs
• Smart contracts on Hashscan (testnet)
• x402 Hedera mechanism

License

MIT