httb API Reference

The Bitcoin wallet for AI agents · httb.sh

# overview

httb is the Bitcoin wallet for AI agents — both sides of the market. Agents spend on services they need and earn sats when other agents call theirs. Register an endpoint once and get paid per call, automatically, over Lightning.

spend

pay for services

Agents pay any L402 URL or httb registry service. No Lightning node, no invoice handling — just a balance.

earn

get paid per call

fund

Deposit sats via Lightning. Balance shared across all your agents.

connect

Add httb to your MCP config. Agents get 8 tools instantly.

earn

# quickstart

httb is in private beta. Request access at httb.sh, then:

bash

# 1. Sign in at https://httb.sh
# 2. Dashboard → Agents → New Agent → copy your API key (shown once)
# 3. Dashboard → Wallet → Deposit sats via Lightning

# Option A — MCP (Claude, Cursor, any MCP-compatible agent)
{
  "mcpServers": {
    "httb": {
      "command": "npx",
      "args": ["-y", "@httb/mcp"],
      "env": { "HTTB_API_KEY": "your_key_here" }
    }
  }
}

# Option B — SDK (add httb payments to any Node/TypeScript app)
npm install httb

typescript

import { HttbClient } from "httb";

const httb = new HttbClient({ apiKey: process.env.HTTB_API_KEY });

// Pay any L402 URL
const result = await httb.pay("https://api.example.com/data");

// Or call a registry service
const svc = await httb.services.invoke("service-id", { query: "hello" });

◆The SDK is ~10KB with zero dependencies. Your agent now has 8 MCP tools: pay_l402, get_balance, search_services, get_service, invoke_service, register_service, list_my_services, get_earnings.

# authentication

Two auth paths — one for agents, one for the dashboard.

agent-apiX-API-Key

API key passed as X-API-Key header. Used for all agent calls (/api/v1/*).

dashboardMagic link

Email sign-in via magic link. Session JWT in cookie. Used for deposits, agent creation, service management.

# mcp-server

8 tools available via MCP:

pay_l402Pay any L402-gated URL from balance

get_balanceCheck balance, daily cap, spend today

search_servicesSearch httb registry by capability

get_serviceGet full details of a specific service

invoke_serviceCall a registry service, balance deducted

register_serviceList your endpoint and earn sats

list_my_servicesSee your registered services

get_earningsTotal sats earned from your registered services

# wallet

Deposit sats via Lightning. Balance shared across all agents.

GET/api/v1/wallet/balanceget balance and spend status

POST/api/v1/wallet/depositcreate Lightning deposit

bash

# Get balance (agent key or session)
curl https://httb.sh/api/v1/wallet/balance \
  -H "X-API-Key: your_key"

# Create Lightning deposit (session auth)
curl -X POST https://httb.sh/api/v1/wallet/deposit \
  -H "Content-Type: application/json" \
  -d '{ "amount_sats": 100000, "type": "LIGHTNING" }'

◆Deposits are Lightning only — minimum 100 sats.

# pay-l402

Pay any URL that returns HTTP 402. httb handles the Lightning invoice automatically.

POST/api/v1/paypay any L402-gated URL

bash

curl -X POST https://httb.sh/api/v1/pay \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/data",
    "method": "POST",
    "payload": { "query": "example" }
  }'

Cost: invoice amount + max(50 sats, 1% of invoice). Balance refunded if the URL fails after payment.

# registry

Browse and call agent-native services. Provider details are never exposed.

GET/api/v1/servicessearch — ?q=, category=, max_price=, sort=

GET/api/v1/services/:idget service details and schema

POST/api/v1/services/:id/invokecall service, balance deducted

bash

# Search
curl "https://httb.sh/api/v1/services?q=translate&max_price=100" \
  -H "X-API-Key: your_key"

# Invoke
curl -X POST https://httb.sh/api/v1/services/{id}/invoke \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{ "payload": { "text": "hello", "target_lang": "es" } }'

◆Cost = listing_price_sats. Balance is refunded automatically if the provider fails or times out.

# register-service

Turn any HTTP endpoint into a sats-earning service. Register once — agents find it, call it, and httb pays you over Lightning per call. No subscription, no contracts. You set the price.

◆Your earnings go directly to your Lightning address each time a call completes. httb keeps 0.9% (min 10 sats); you keep the rest. No monthly fee, no setup fee.

POST/api/v1/servicesregister service — returns endpoint_secret once

json

{
  "name": "Spanish Translator",
  "description": "Translate text to Spanish",
  "category": "translation",
  "provider_endpoint": "https://your-api.com/translate",
  "provider_lightning_address": "you@walletofsatoshi.com",
  "provider_price_sats": 10,
  "input_schema": {
    "type": "object",
    "required": ["text"],
    "properties": { "text": { "type": "string" } }
  },
  "output_schema": {
    "type": "object",
    "properties": { "translated": { "type": "string" } }
  }
}

◆Validate all incoming calls by checking the X-HTTB-Secret header matches your endpoint_secret. Secret shown once at registration.

# response-format

All responses follow this envelope:

json

// Success
{
  "ok": true,
  "data": { ... },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2025-01-01T00:00:00Z",
    "satsSpent": 100
  }
}

// Error
{
  "ok": false,
  "error": "Insufficient balance",
  "code": "INSUFFICIENT_BALANCE",
  "hint": "Deposit more sats at https://httb.sh/dashboard/wallet"
}

# error-codes

INSUFFICIENT_BALANCEDeposit more sats

DAILY_CAP_EXCEEDEDCap resets at midnight UTC

SERVICE_NOT_FOUNDUse search_services() to find valid IDs

SERVICE_TIMEOUTRetry once, then try an alternative

SERVICE_ERRORBalance refunded, try an alternative

INVALID_PAYLOADCheck service input_schema

INVALID_API_KEYCheck HTTB_API_KEY environment variable

AGENT_INACTIVERe-enable agent in dashboard

L402_PARSE_ERRORTarget URL may not support L402

L402_PAYMENT_FAILEDRetry — Lightning routing issue