Engine Client

The OneEngineClient is the single entry point for all server communication in the ONE SDK. This page covers construction, configuration, token management, and the request lifecycle.

Import

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

Factory Function

function createOneEngineClient(options?: OneEngineClientOptions): OneEngineClient;

OneEngineClientOptions

interface OneEngineClientOptions {
  /** Base URL for the ONE Engine API. Defaults to "https://engine.one23.io". */
  engineUrl?: string;
  /** Project client ID from the dashboard. */
  clientId: string;
  /** Project secret key from the dashboard. */
  secretKey: string;
}

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 obtained from the ONE dashboard.
secretKey	string	Yes	--	Project secret key obtained from the ONE dashboard.

Basic Construction

const engine = createOneEngineClient({
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

Custom Engine URL

Point the client at a staging or self-hosted instance:

const engine = createOneEngineClient({
  engineUrl: 'https://staging-engine.one23.io',
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

Access Token Management

Protected endpoints require a Bearer token. After authenticating a user, store the token on the client instance.

setAccessToken

engine.setAccessToken(token: string): void;

Parameter	Type	Required	Description
token	string	Yes	JWT access token returned by an auth method.

Example Flow

// 1. Create the engine client
const engine = createOneEngineClient({
  clientId: 'proj_abc123',
  secretKey: 'sk_live_xyz789',
});

// 2. Authenticate (email OTP flow)
const otpRes = await engine.sendEmailOtp('user@example.com');
// ... user enters the OTP code ...
const authRes = await engine.verifyEmailOtp('user@example.com', '123456');

if (authRes.success && authRes.data) {
  // 3. Store the token on the client
  engine.setAccessToken(authRes.data.accessToken);
}

// 4. Now call protected endpoints
const walletRes = await engine.getWalletBalance('0xABC...');

Request Lifecycle

Every method follows the same internal flow:

1. Serialize parameters to JSON body or query string.
2. Attach headers:
   - x-client-id: <clientId>
   - x-secret-key: <secretKey>
   - Authorization: Bearer <accessToken>  (if set)
   - Content-Type: application/json
3. Send HTTP request to engineUrl + endpoint path.
4. Parse JSON response into ApiResponse<T>.
5. Return { success, data?, error? }.

Request Headers

Header	Source	Always Sent
x-client-id	clientId from options	Yes
x-secret-key	secretKey from options	Yes
Authorization	Bearer <token> via setAccessToken	Only when token is set
Content-Type	application/json	Yes

Response Handling

All methods return ApiResponse<T>:

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

Success Path

const res = await engine.getCurrentUser();
if (res.success) {
  console.log('User:', res.data);
}

Error Path

const res = await engine.getCurrentUser();
if (!res.success) {
  console.error('Failed:', res.error);
  // res.error is a human-readable string like "unauthorized"
}

Singleton Pattern (React)

In React applications the client is typically created once and shared via context:

// lib/engine.ts
import { createOneEngineClient } from '@one_deploy/sdk';

export const engine = createOneEngineClient({
  clientId: process.env.NEXT_PUBLIC_ONE_CLIENT_ID!,
  secretKey: process.env.NEXT_PUBLIC_ONE_SECRET_KEY!,
});

When using OneProvider, the provider creates and manages the client internally. Access it through the useOneEngine hook:

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

function MyComponent() {
  const engine = useOneEngine();
  // engine is a fully configured OneEngineClient
}

React Native -- Cached Client

For React Native, use the cached factory to avoid re-creating the client on every render:

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

const engine = createCachedEngineClient({
  clientId: 'proj_abc123',
  secretKey: 'sk_live_xyz789',
});

This returns the same instance on subsequent calls with identical options.

Next Steps

• Auth API -- authenticate users and obtain an access token.
• Wallet API -- query balances and send transactions.
• API Reference Overview -- full method index.