API Reference Overview

The OneEngineClient is the central API client shipped in @one_deploy/sdk v1.1.0. It exposes 91+ methods covering authentication, wallets, swaps, fiat on/off-ramp, AI trading, forex, contracts, NFTs, billing, staking, bridges, gas estimation, pricing, webhooks, admin, and project management.

Creating the Client

Use the createOneEngineClient factory to instantiate the client.

import { createOneEngineClient } from '@one_deploy/sdk';

const engine = createOneEngineClient({
  engineUrl: 'https://engine.one23.io',
  clientId: 'your-client-id',
  secretKey: 'your-secret-key',
});

Factory Signature

function createOneEngineClient(options?: OneEngineClientOptions): OneEngineClient;

Configuration Options

Option	Type	Required	Default	Description
engineUrl	string	No	https://engine.one23.io	Base URL for the ONE Engine API.
clientId	string	Yes	--	Project client ID from the dashboard.
secretKey	string	Yes	--	Project secret key from the dashboard.

Response Pattern

Every method returns a typed ApiResponse<T> envelope so you can handle success and error paths consistently.

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

Consuming a Response

const res = await engine.getWalletBalance('0xABC...', ['ethereum']);

if (res.success) {
  console.log('Balances:', res.data);
} else {
  console.error('Error:', res.error);
}

Authentication

Most endpoints require a Bearer token. After authenticating (email OTP or wallet signature), call setAccessToken on the client instance.

// After successful auth
engine.setAccessToken(authResponse.accessToken);

All subsequent requests include the header:

Authorization: Bearer <token>

tip

The free Price API endpoints do not require authentication. You can call them without setting an access token.

Base URL Configuration

By default the client targets https://engine.one23.io. Override this for staging or self-hosted deployments:

const engine = createOneEngineClient({
  engineUrl: 'https://staging-engine.one23.io',
  clientId: 'your-client-id',
  secretKey: 'your-secret-key',
});

Error Handling Patterns

Basic Try/Catch

try {
  const res = await engine.getWalletBalance('0xABC...');
  if (!res.success) {
    // API returned an error payload
    console.error('API error:', res.error);
    return;
  }
  // Use res.data safely
} catch (err) {
  // Network or unexpected error
  console.error('Network error:', err);
}

Centralised Error Handler

async function safeCall<T>(fn: () => Promise<ApiResponse<T>>): Promise<T | null> {
  try {
    const res = await fn();
    if (!res.success) {
      console.error('[API Error]', res.error);
      return null;
    }
    return res.data ?? null;
  } catch (err) {
    console.error('[Network Error]', err);
    return null;
  }
}

// Usage
const balance = await safeCall(() => engine.getWalletBalance('0xABC...'));

Common Error Strings

Error	Meaning
"unauthorized"	Missing or expired access token. Call setAccessToken or re-authenticate.
"forbidden"	The authenticated user does not have the required role (e.g., admin).
"not_found"	The requested resource does not exist.
"rate_limited"	You have exceeded your project's rate limit. Back off and retry.
"validation_error"	One or more request parameters failed validation. Check the error string for details.
"internal_error"	Server-side error. Retry with exponential back-off.

Method Index

The client groups its 91+ methods into the following API surfaces. Click through to each page for full parameter and return-type documentation.

API Surface	Methods	Page
Auth	6	Auth API
Wallet	7	Wallet API
Swap	5	Swap API
On-ramp / Off-ramp	10	On-ramp & Off-ramp API
AI Trading	18+	AI Trading API
Forex	8+	Forex API
Contracts & NFTs	9	Contracts & NFTs API
Bills & Staking	9	Bills & Staking API
Bridge & Gas	6	Bridge & Gas API
Price (Free)	5	Price API
Webhooks	7	Webhooks API
Admin	11	Admin API
Project	8	Project API

TypeScript Support

All request and response types are exported from the package root:

import type {
  ApiResponse,
  OneEngineClientOptions,
  EngineAuthResponse,
  EngineWalletBalance,
  SwapQuote,
  // ... all other types
} from '@one_deploy/sdk';

Next Steps

• Engine Client -- detailed construction and configuration.
• Auth API -- authenticate users before calling protected endpoints.
• Price API -- free endpoints that work without auth.