API Overview

API Structure

The Builder Service provides two main API interfaces:

HTTP API

Traditional RESTful API for:

• One-time operations
• Auth / delegate wallet management
• Balance queries
• Health checks
• Standard trading operations

WebSocket API

Real-time bidirectional communication for:

• Live trading operations
• Market data streaming
• Low-latency order management
• Continuous connection scenarios

Base URLs

Production

• HTTP: https://builder.ostiscan.xyz/v1
• WebSocket: wss://builder.ostiscan.xyz/v1/exchange/ws

Local Development

• HTTP: http://localhost:3000/v1
• WebSocket: ws://localhost:3000/v1/exchange/ws

Authentication

All requests require trader identification:

Required Header

X-Trader-Address: 0xYourWalletAddress

Optional Header (Delegated Mode)

X-API-Key: your-api-key

Response Formats

Success Response (Default Mode)

{
  "transactions": [
    {
      "to": "0xContractAddress",
      "data": "0xEncodedCalldata",
      "value": "0",
      "from": "0xYourWallet"
    }
  ]
}

Success Response (Delegated Mode)

{
  "txHash": "0xTransactionHash",
  "smartAccountAddress": "0xSmartAccountAddress"
}

Error Response

{
  "error": "Human-readable error message",
  "code": 400,
  "errorCode": "VALIDATION_ERROR",
  "details": {
    "field": "Additional context"
  }
}

Common Headers

Request Headers

• Content-Type: application/json - Required for POST requests
• X-Trader-Address - Required, trader wallet address
• X-API-Key - Optional, enables delegated mode
• X-Request-ID - Optional, for request tracking

Response Headers

• X-Request-ID - Echo of request ID or generated
• X-RateLimit-Limit - Rate limit ceiling
• X-RateLimit-Remaining - Requests remaining
• X-RateLimit-Reset - Seconds until reset

OpenAPI Specification

The service provides OpenAPI 3.0 specification:

• Interactive Documentation: https://builder.ostiscan.xyz/openapi
• JSON: GET /v1/openapi.json
• YAML: GET /v1/openapi.yaml
• HTML: GET /v1/openapi

Use the interactive documentation to explore the API or download the specification to generate client libraries and integrate with tools like Postman or Insomnia.

Next Steps

• Explore the HTTP API endpoints
• Learn about WebSocket trading
• Review error handling