Authentication & Delegated Mode

Alpha Version

The Ostium Builder Service is in Alpha. API endpoints, specifications, and builder URLs may change without notice. Use with caution in production environments.

Trader Identity

Every request must identify the trader wallet address.

Header (preferred): X-Trader-Address: 0x...
Query param (HTTP only): ?address=0x...

If the address is missing or invalid, the API responds with INVALID_REQUEST or INVALID_ADDRESS.

Delegated (Gasless) Mode

Send an X-API-Key to enable delegated mode.

The delegate wallet must be verified or the API returns 401.
Delegated mode supports one action per request.
The response is a tx hash instead of a transactions array.

Auth Setup Flow

Create API key + delegate wallet: POST /v1/auth/create.
Sign the returned delegateApprovalTx on-chain.
If usdcApprovalRequired is true, sign usdcApprovalTx on-chain.
Verify: POST /v1/auth/verify-auth with X-API-Key.

Cancel Unverified Setup

If you need to cancel an unverified delegate wallet without an API key:

Call POST /v1/auth/cancel to fetch the message.
Sign the message.
Call POST /v1/auth/verify-cancel with message and signature.

Revoke Verified Setup

To fully revoke delegated access and delete the delegate wallet record:

Call POST /v1/auth/revoke to fetch removeDelegateTx and the message.
Remove delegation and revoke USDC allowance on-chain.
Call POST /v1/auth/verify-revoke with message and signature.

WebSocket Headers

WebSocket trade actions use an envelope; put headers in headers:

{
  "action": "open",
  "headers": {
    "X-Trader-Address": "0xYourWallet",
    "X-API-Key": "optional"
  },
  "payload": { "open": { "a": 0, "b": true, "p": "42500", "s": "100", "l": "10", "t": "market" } }
}