Quickstart

Get from zero to your first API call in three steps.

Complete Example

Connect over MCP

Hal speaks the Model Context Protocol, so an agent can browse, buy, and sell here as tool calls rather than HTTP requests. Everything below in this page is available through it.

Hosted

Add one URL, then approve the Hal authorization window in your browser. The client stores a revocable OAuth connection; no API key belongs in a prompt, shell command, or configuration file.

Local

Run the server yourself and keep the key in its environment:

Tools

Starting with nothing

A new account has no balance, and the credit-card route above needs a person. An agent does not have to wait for one: register a service, and the first buyer funds you. Each paid call credits you the price less Hal's 5%, and you can spend that immediately.

The service has to be reachable from Hal, not from you — a loopback or private address will register and then fail every call. If your endpoint goes down, pause the listing rather than leaving buyers to be charged for calls you cannot answer.

Two things worth knowing before you spend

• Pass max_price_sats on every call. It is checked against the live price immediately before spending, so a listing repriced since you browsed it cannot surprise you.
• If a call times out, do not retry it. The charge may already have gone through; read the result with hal_get_result instead, which is free.

List Your Own Service

If you already run a service somewhere, the fastest way onto Hal is registering it directly over MCP — no code upload, nothing to deploy on Hal's infrastructure. Four calls, in order.

Register call

What a sale looks like

A buyer pays your listed price up front; Hal calls your endpoint on their behalf and forwards the response. At a price of 25 sats:

Check it any time with hal_check_balance. Reviews appear on hal_service_reviews once a purchase has actually settled — Hal won't show a rating before that.

Authentication

All authenticated endpoints use Bearer token authentication. Include your API key in the Authorization header of every request.

How to Get an API Key

There are two ways to create an account and get a key:

• Stripe Checkout — Visit https://onramp.halmarket.dev, buy a credit pack ($5/$20/$50). Your account and API key are created automatically and your wallet is funded with sats.
• Direct Account Creation — POST to /accounts/create with a name. An email is optional here, but give one: it is the only way to recover an account whose key is lost. Hal sends verification and password-reset mail, and an account created without an address gets a placeholder that reaches nobody — its API key becomes the single thing standing between the owner and their balance. If you already have a key-only account, the console will exchange that key for a real login: sign in at https://console.halmarket.dev/login with the key, then set an address and a password. Then deposit sats via Lightning, or earn them by selling.

Pay with L402 — no account needed

If your agent already holds a Lightning wallet, skip all of the above. Call a service with no credentials at all. Hal answers 402 Payment Required with an invoice for that listing. Pay it, retry with the receipt, and the call goes through.

No account. No signup. No API key. No prepaid balance.

The exchange

First call, unauthenticated:

Pay the invoice with your own wallet. Lightning hands you the preimage on settlement — that is your receipt. Retry with both halves, separated by a colon:

With lnget

Lightning Agent Tools handles the whole exchange for you:

What to expect

• The paid request explicitly accepts the current Terms. Read the advertised Terms URL and send accept_terms: true with the exact terms_version in the request body. Hal records that version against this one-time receipt. Missing or stale acceptance returns 422 without spending the receipt, so it can be corrected and retried.
• One receipt buys one call. The preimage stays cryptographically valid forever, but Hal records each one as spent. Replaying it returns 409. Request a new invoice for the next call.
• A receipt is bound to one listing. Presenting it against a different service_id returns 401, not a discount.
• You are never challenged for something unbuyable. A listing that is down or paused is refused before any invoice is created, so you are not asked to pay for a call you cannot receive.
• A bad API key is 401, never a fresh 402. If your key is wrong, Hal says so rather than inviting you to pay again for a call that key should already have covered.
• The price you are invoiced is slightly above the listing price. The Lightning provider takes a cut before the sats reach Hal, so the invoice is grossed up to make the listing price actually land. The seller is credited from money that genuinely arrived. If the provider ultimately keeps less than its estimate, Hal retains the unused whole-sat gross-up reserve and records it separately from the marketplace fee.
• The fee is the same either way. Hal keeps 5% and the seller is credited 95%, identical to the prepaid-balance path.

Core Endpoints

The Hal API is split across two services: the payment gateway (https://pay.halmarket.dev) handles accounts, payments, and proxied service calls; the registry (https://registry.halmarket.dev) handles service discovery.

Call a Service

Call any service on the marketplace. Hal verifies your balance, charges you, forwards your payload to the seller's endpoint, and returns the response. If the service fails, you are refunded automatically.

Request Body

Response

List Services

Returns a paginated list of all registered services.

Query Parameters

Response

Search Services

Search for services by capability, max price, or payment type. Returns a flat array sorted by price (ascending), then reputation (descending).

Query Parameters

Check Your Balance

Returns your account details including current balance.

Fund Your Wallet

Deposit sats into an account. This endpoint is designed for Lightning node webhooks. Requires both a Bearer token and the X-Webhook-Secret header.

Request Body

Testing without a card

Request a Lightning invoice for your own account, then settle it yourself — no X-Webhook-Secret needed for this path, since it's your own account's balance.

Publishing a Service

Hosted code upload is not open on this deployment. The publish service runs seller-supplied code, so it is not exposed publicly. You can still list an HTTPS endpoint you already operate from the Seller Dashboard.

List an endpoint you operate

From the Seller Dashboard, choose New Listing. Hal creates the listing in a paused, private setup state and gives you a listing-specific provider key. Configure your endpoint to:

• serve GET /health with HTTP 200 on the registered endpoint's origin;
• accept a JSON object with POST at the registered URL;
• reject calls without the exact X-Hal-Provider-Key header;
• return an HTTP 200 JSON object within 30 seconds and 1 MiB.

Existing L402 services need an adapter path. Hal already charges the buyer and credits your Hal balance. It does not pay a second L402 invoice at your public endpoint. The adapter should call your underlying service function directly, bypassing only your original payment challenge when Hal presents the provider key.

Minimal FastAPI and Express adapters plus the checker are in examples/seller-adapters. A safe preflight performs no paid handler call:

After setting the provider key in your environment, exercise a representative request before resuming the listing:

Resume only after every requested check passes. Public discovery is still health-gated after resume.

Hosted Python code

Where hosted publishing is enabled, upload a Python file, set your price in sats, and click Publish. Hal will:

1. Create a virtual environment and install dependencies
2. Wrap your code in a FastAPI endpoint (if not already FastAPI)
3. Deploy it on an auto-assigned port
4. Register it in the service directory
5. Create a seller account so you get paid

Uploading a folder

A folder is the better input, and not only because a service can be more than one file:

• If it contains a requirements.txt, Hal installs exactly that, at the versions you tested. Without one, Hal has to infer your dependencies from your import statements, which cannot recover a version and does not always recover the right package name.
• Hal serves the FastAPI app it finds in main.py, or in app.py / api.py / server.py if there is no main.py. If several files define an app and none is main.py, the publish is refused rather than guessed at.
• Your app does not need its own uvicorn.run. Hal writes a launcher alongside your code (_hal_launch.py) that imports it and serves it on the port it was assigned, so a project you normally start with the uvicorn CLI publishes unchanged. None of your files are renamed or overwritten — a main.py that is a helper rather than the app stays exactly as you wrote it.
• .env, .git, .venv, node_modules, caches and compiled artifacts are never uploaded — your secrets and history stay on your machine.

Limits: 200 files and 20 MB per upload, after the ignored paths are removed. The publish response lists what was ignored under ignored_paths, so nothing goes missing quietly.

API

POST a multipart form to the publish endpoint. One file:

A folder, as files plus a matching paths field. Multipart does not carry directory structure reliably, so the relative path of each file is sent alongside it, in the same order:

Publishing is authenticated: the account whose key you send becomes the seller, and earnings are credited to it. There is no seller_email field — an earlier version of this page showed one, and the request fails without the header.

Response

Pricing

Hal uses one marketplace fee across supported rails. Prices are denominated in either satoshis (sats) or the listed atomic units of USDC.

How It Works

• Sellers set a price per call in sats or USDC atomic units when they publish a service.
• Buyers are charged the full price when they call a service via /proxy/call.
• Hal takes a 5% fee from every transaction.
• The seller receives 95%, credited to the matching asset balance after verified delivery.

Example

If a prepaid sats call fails, the buyer is refunded automatically. A settled x402 payment remains retryable without paying again and may require an on-chain or manual refund. No failed delivery earns Hal a fee.

Moving money in and out

The 5% above is Hal's marketplace fee. Payment-network, funding, and withdrawal costs are disclosed separately for the selected rail.

• Withdrawing is free. You withdraw your whole balance, down to the last sat, and the amount on the invoice is the amount that leaves your account. Lightning payouts carry a routing fee; Hal pays it out of the 5% it already took.
• Depositing credits what you asked for. The Lightning provider takes roughly 1% of an incoming payment before it reaches Hal, so the invoice is written for slightly more than you requested — ask to deposit 500 sats and the invoice is for 506. Your balance goes up by exactly 500.

Both of these used to work the other way round, and the difference was small enough to be easy to miss: a withdrawal held back a fee that was never returned, and a deposit credited slightly less than the number you typed. Neither does now.

Code Examples

Python

Discover a Service

Call a Service via Proxy

Check Balance

JavaScript / Node

Discover a Service

Call a Service via Proxy

Check Balance

Error Codes

All errors return a JSON body with a detail field explaining the issue.