x500

Command-line tool for x500 — insured API calls and x402 Exact HBAR payments on Hedera testnet.

Wraps x500-sdk for quick testing, scripting, and CI. All amounts are HBAR tinybars (asset: 0.0.0). USDC / HTS is not supported in V1.

V1 scope: --network testnet only.

Install

npm install -g x500

Or run without installing:

npx x500 --network testnet balance

Requires Node.js 18+.

Setup

Export your Hedera testnet agent credentials:

export X500_AGENT_ACCOUNT_ID=0.0.1234567
export HEDERA_AGENT_PRIVATE_KEY=0xabc123...

Optional — override default Cloud Run service URLs for local dev:

export MARKET_PROXY_URL=http://127.0.0.1:8788
export INDEXER_URL=http://127.0.0.1:8787
export FACILITATOR_URL=http://127.0.0.1:8790

Check wallet balance:

x500 --network testnet balance

Fund insurance escrow (one-time depositEscrow on X500Pool):

x500 --network testnet approve

Deposits 0.1 HBAR (10,000,000 tinybars) by default. HBAR needs no HTS token association.

Commands

Insured fetch (default)

Pass a URL as the first argument. Output is JSON.

# Merchant origin URL — slug resolved via indexer
x500 --network testnet https://your-merchant.example/paid/weather?city=Tokyo

# Explicit proxy path
x500 --network testnet /v1/my-slug/paid/weather?city=Tokyo

Example response:

{
  "status": 200,
  "callId": "…",
  "premiumTinybars": "1000000",
  "refundTinybars": "0",
  "outcome": "ok",
  "asset": "0.0.0",
  "body": { … }
}

balance

Wallet HBAR balance for X500_AGENT_ACCOUNT_ID.

x500 --network testnet balance

{
  "accountId": "0.0.1234567",
  "network": "hedera:testnet",
  "asset": "0.0.0",
  "tinybars": "500000000",
  "hbar": "5.00000000"
}

approve

Deposit escrow for insurance premiums (X500Pool.depositEscrow).

x500 --network testnet approve

{
  "ok": true,
  "note": "HBAR needs no token association; deposited escrow via depositEscrow",
  "transactionId": "0.0.1234567@…"
}

pay

x402-only payment — no insurance wrap. Useful for testing merchant x402 routes directly.

x500 --network testnet pay https://merchant.example/paid/quote

calls show <callId>

Fetch call detail from the indexer (settlement tx, outcome, premiums).

x500 --network testnet calls show 01234567-89ab-cdef-0123-456789abcdef

agents show [accountId]

Agent stats and escrow info. Defaults to your X500_AGENT_ACCOUNT_ID.

x500 --network testnet agents show
x500 --network testnet agents show 0.0.1234567

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | X500_AGENT_ACCOUNT_ID | Yes | Hedera account 0.0.x | | HEDERA_AGENT_PRIVATE_KEY | Yes | ECDSA hex private key | | MARKET_PROXY_URL | No | Insured gateway base URL | | PROXY_URL | No | Alias for MARKET_PROXY_URL | | INDEXER_URL | No | Indexer REST API base URL | | FACILITATOR_URL | No | x402 facilitator URL | | X500_DEPLOYMENTS_PATH | No | Path to deployments.testnet.json | | X500_POOL_CONTRACT_ID | No | Pool contract for escrow (default 0.0.9585433) |

When unset, URLs default to the live x500 testnet Cloud Run stack.

Typical workflow

# 1. Credentials
export X500_AGENT_ACCOUNT_ID=0.0.x
export HEDERA_AGENT_PRIVATE_KEY=0x...

# 2. Check funds
x500 --network testnet balance

# 3. Deposit insurance escrow
x500 --network testnet approve

# 4. Call a registered merchant API
x500 --network testnet https://your-ngrok-url.ngrok-free.app/paid/weather?city=London

# 5. Inspect settlement
x500 --network testnet calls show <callId-from-response>

Merchants must register their public origin URL in the x500 dashboard before insured calls succeed.

Programmatic use

For agents, LangChain tools, and production integrations, use x500-sdk instead:

npm install x500-sdk

Links

• x500-sdk on npm
• x500 monorepo & full docs
• Example agent + merchant server

License

MIT