API access

Khalani issues API keys during onboarding. There is no self-serve sign-up. With your key you receive:

• Your integrator name, which scopes your orders. Error messages identify you by its integratorId, the keccak256 hash of the name.
• Your commercial terms: your commission in basis points and the hub wallet it is paid to. They live in an on-chain integrator registry that the hub contract reads when each order publishes, so no request can change them.
• Your order deadline (orderTtl): how long each order stays open after the build. It is an API setting that every build signs into its order.

Read all of them with GET /v2/params.

Send the key from your backend

Send the key in the X-API-Key header:

curl -s https://api.hyperstream.dev/v2/params -H "X-API-Key: $KHALANI_API_KEY"

Call the API from your backend only. CORS is open (*) for convenience, not permission: a key shipped in a browser or app bundle is a key anyone can use.

Route	Auth
GET /v2/params	API key
GET /v2/quote	API key
POST /v2/build	API key
GET /v2/orders	API key
POST /v2/orders/{orderId}/cancel	API key
GET /v2/orders/{orderId}	Public: the orderId is the credential
GET /v2/health	Public

What a key can do

One key is your whole integration. It can build orders under your name, list every order you built along with each depositor and recipient, and read your terms.

It cannot move funds. A deposit is a transaction the user signs, and a cancel needs the user’s signature. A leaked key cannot spend anyone’s tokens, but it can build orders under your name and read your order history, so treat it as a secret.

Keys have no scopes and no expiry. Rotation is arranged with Khalani: the old key keeps working for an agreed grace period. A change to your terms can take up to 60 seconds to show.

Authentication errors

Status	error	Meaning
401	X-API-Key required	The header is missing.
403	Unknown or inactive integrator	The key is not recognised, or its rotation grace period has ended.
403	Integrator <integratorId> is not enabled on the integrator registry	The key is valid, but your account is disabled or not set up yet.
403	Integrator <integratorId> owes a commission with no wallet configured	Your terms are invalid.
403	Integrator <integratorId> carries a fee at or above 100%	Your terms are invalid.
503	Integrator terms are temporarily unreadable	Your terms could not be read from the hub. This says nothing about your key. Retry.

A 403 is always about your account and a 503 never is, so retry logic can treat every 403 as final. Contact Khalani through your onboarding channel to resolve one.

Check that you are ready

GET /v2/params is the readiness check for your key. It reflects your account, is not rate limited, and keeps working during maintenance. A 200 means your key works and your account is enabled; a 403 names the problem. The tokens list is the same for every integrator.

GET /v2/health is not a readiness check. It reports the order pipeline across all integrators.