HTTP Overview

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.

Base Path

All HTTP endpoints are served under /v1.

Content Types

Requests must be JSON and may use either header:

Content-Type: application/json
Content-Type: text/plain (JSON string body)

Authentication Headers

X-Trader-Address (required): trader wallet address
X-API-Key (optional): required for delegated mode

Header matching is case-insensitive.

Data Types

Prices and USD amounts are strings to preserve precision (example: "42500.25").
Leverage is a string (example: "10" for 10x).
Indexes are integers (a, i, t, o).

Trader Address Fallback

For HTTP only, you may pass the trader address as a query param:

?address=0x...

Headers are preferred and always take priority when both are present.

Request ID

You may send X-Request-ID to tag a request. If omitted, the service generates one. The response always includes the request ID as X-Request-ID.

Rate Limits

HTTP requests are rate-limited per IP. When limits apply, the response includes:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset (seconds until reset)
Retry-After (on 429)

See /docs/rate-limits for configuration details.

Common Response Shapes

Unsigned Transactions

Returned by default (non-delegated mode).

Field	Type	Required	Description
`transactions`	`UnsignedTransaction[]`	Yes	One or more unsigned transactions to sign and submit.

UnsignedTransaction

Field	Type	Required	Description
`to`	`string`	Yes	Contract address.
`data`	`string`	Yes	ABI-encoded calldata.
`value`	`string`	Yes	ETH value (usually `"0"`).
`from`	`string`	No	Trader address (when provided by the service).

Delegated Mode Response

Returned when X-API-Key is present and the delegate wallet is verified.

Field	Type	Required	Description
`txHash`	`string`	Yes	Transaction hash of the delegated action.
`smartAccountAddress`	`string`	Yes	Smart account used for delegation.

Error Response (HTTP)

Field	Type	Required	Description
`error`	`string`	Yes	Human-readable error message.
`code`	`number`	Yes	HTTP status code.
`errorCode`	`string`	Yes	Machine-readable error code.
`details`	`object`	No	Extra context (e.g., validation errors).

Common errorCode values:

VALIDATION_ERROR
INVALID_REQUEST
INVALID_ACTION
INVALID_ADDRESS
NOT_FOUND
UNAUTHORIZED
RATE_LIMIT_EXCEEDED
INTERNAL_ERROR
SERVICE_UNAVAILABLE

See /docs/errors for the full error envelopes.

OpenAPI

The service exposes its OpenAPI spec:

Interactive Documentation: https://builder.ostiscan.xyz/openapi
GET /v1/openapi
GET /v1/openapi.json
GET /v1/openapi.yaml

HTTP Overview

Alpha Version

On this page