Yamata Adapter SDK


> JavaScript SDK for Yamata Trading Platform - A comprehensive Binance-compatible API wrapper with blockchain integration, providing seamless access to market data, account management, and API key management features (GET requests only).

🎯 What is Yamata Adapter SDK?

The Yamata Adapter SDK is a powerful JavaScript library that provides a Binance-compatible interface to the Yamata trading platform. It acts as a bridge between your applications and Yamata's blockchain-powered trading infrastructure, offering:

- Familiar Binance API patterns for easy migration
- Blockchain integration for secure trading operations
- Real-time market data and WebSocket streaming
- Account management and API key handling
- API key management and permissions

$3

- Trading Bots: Build automated trading strategies
- Portfolio Management: Monitor and manage trading positions
- Market Analysis: Access real-time market data and analytics
- Exchange Integration: Connect existing applications to Yamata
- DeFi Applications: Integrate with blockchain-based trading

✨ Features

$3

- HMAC-SHA256 signature authentication
- API key management with granular permissions
- Secure secret key handling
- Timestamp validation and replay attack prevention

$3

- Real-time ticker information
- Order book depth data
- Historical candlestick data (klines)
- Recent trades and market activity
- Exchange information and symbol details

$3

- Account information and balances
- Trade history and order tracking
- Account status monitoring

$3

- API key listing and statistics
- Permission management
- Key status monitoring

$3

- WebSocket support for live data
- Event-driven architecture
- Automatic reconnection handling
- Low-latency market updates

📚 Documentation

For comprehensive documentation, visit our Documentation Hub:

- 🚀 Quick Start Guide - Get up and running in minutes
- 📖 API Reference - Complete API documentation
- 🏗️ Technical Documentation - Architecture and implementation details

📦 Installation

$3

- Node.js 18+
- npm or yarn package manager

$3

``bash
npm install yamata-adapter-sdk
`

Or using yarn:

`bash
yarn add yamata-adapter-sdk
`

$3

Create a .env file in your project root:

`env


Yamata API Configuration

YAMATA_API_KEY=ymta_your_api_key_here
YAMATA_SECRET_KEY=your_secret_key_here
YAMATA_BASE_URL=http://localhost:3080
YAMATA_TEST_USER_ID=your_test_user_id

Optional Configuration

YAMATA_RECV_WINDOW=5000
YAMATA_TIMEOUT=30000
YAMATA_DEBUG=false
`

🔧 Quick Integration Checklist

Before you start, ensure you have:

- [ ] API Keys: Valid Yamata API key (starts with ymta_)
- [ ] Secret Key: Corresponding secret key for signature generation
- [ ] Base URL: Yamata adapter service URL (default: http://localhost:3080)
- [ ] User ID: Valid user ID for API key creation (if needed)
- [ ] Network Access: Connection to Yamata adapter service

🚀 SDK Initialization

$3

`javascript
import { YamataAdapterSDK } from 'yamata-adapter-sdk';

// Initialize with configuration
const sdk = new YamataAdapterSDK({
apiKey: 'ymta_your_api_key_here',
secretKey: 'your_secret_key_here',
baseUrl: 'http://localhost:3080',
debug: true
});
`

$3

`javascript
const sdk = new YamataAdapterSDK({
// Required
apiKey: process.env.YAMATA_API_KEY,
secretKey: process.env.YAMATA_SECRET_KEY,
baseUrl: process.env.YAMATA_BASE_URL || 'http://localhost:3080',

// Optional
debug: process.env.NODE_ENV === 'development',
timeout: 30000,
recvWindow: 5000,
retries: 3,
retryDelay: 1000
});
`

$3

`javascript
import { YamataAdapterSDK } from 'yamata-adapter-sdk';

const sdk = new YamataAdapterSDK({
apiKey: process.env.YAMATA_API_KEY || 'ymta_test_api_key_1234567890abcdef',
secretKey: process.env.YAMATA_SECRET_KEY || 'test_secret_key_1234567890abcdef',
baseUrl: process.env.YAMATA_BASE_URL || 'http://localhost:3080',
debug: process.env.NODE_ENV === 'development'
});

📚 API Reference & Usage Examples

$3

#### Public APIs (No Authentication Required)
1. Health & Connectivity APIs
- 1.1 Health Check
- 1.2 Ping
- 1.3 Get Clients
- 1.4 Get Time

2. Exchange Information APIs
- 2.1 Get Exchange Info
- 2.2 Get Cached Symbols

3. Market Data APIs
- 3.1 Get 24hr Ticker (All Symbols)
- 3.2 Get 24hr Ticker (Specific Symbol)
- 3.3 Get Ticker Price (All Symbols)
- 3.4 Get Ticker Price (Specific Symbol)

4. Order Book APIs
- 4.1 Get Depth (Order Book)
- 4.2 Clear Depth Cache

5. Recent Trades APIs
- 5.1 Get Recent Trades

6. Candlestick Data APIs
- 6.1 Get Klines (Candlesticks)

#### Authenticated APIs (Requires API Key)
7. Account Management APIs
- 7.1 Get Account Information
- 7.2 Get Account Balance
- 7.3 Get Account Status
- 7.4 Get My Trades

8. API Key Management APIs
- 8.1 Get API Keys
- 8.2 Get Active API Keys
- 8.3 Get API Key by Name
- 8.4 Get API Key Statistics

---

$3

#### 1.1 Health Check
Check if the Yamata adapter service is running and healthy.

`javascript
try {
const health = await sdk.getHealth();
console.log('Service Status:', health);
// Output: { status: 'ok', timestamp: '2025-08-16T05:06:33.350Z' }
} catch (error) {
console.error('Health check failed:', error.message);
}
`

#### 1.2 Ping
Simple ping to test connectivity and response time.

`javascript
try {
const ping = await sdk.ping();
console.log('Ping Response:', ping);
// Output: { pong: true, timestamp: 1755320793351 }
} catch (error) {
console.error('Ping failed:', error.message);
}
`

#### 1.3 Get Clients
Retrieve information about connected clients and services.

`javascript
try {
const clients = await sdk.getClients();
console.log('Connected Clients:', clients);
// Output: { clients: [...], services: [...], timestamp: ... }
} catch (error) {
console.error('Failed to get clients:', error.message);
}
`

#### 1.4 Get Time
Get the current server time for timestamp synchronization.

`javascript
try {
const serverTime = await sdk.getTime();
console.log('Server Time:', serverTime);
// Output: { serverTime: 1755320793351, timezone: 'UTC' }
} catch (error) {
console.error('Failed to get server time:', error.message);
}
`

$3

#### 2.1 Get Exchange Info
Retrieve comprehensive exchange information including symbols, filters, and trading rules.

`javascript
try {
const exchangeInfo = await sdk.getExchangeInfo();
console.log('Exchange Info:', exchangeInfo);
// Output: {
// timezone: 'UTC',
// serverTime: 1755320793351,
// symbols: [
// {
// symbol: 'BTCUSDT',
// status: 'TRADING',
// baseAsset: 'BTC',
// quoteAsset: 'USDT',
// filters: [...]
// }
// ]
// }
} catch (error) {
console.error('Failed to get exchange info:', error.message);
}
`

#### 2.2 Get Cached Symbols
Get a list of cached trading symbols for quick reference.

`javascript
try {
const cachedSymbols = await sdk.getCachedSymbols();
console.log('Cached Symbols:', cachedSymbols);
// Output: ['BTCUSDT', 'ETHUSDT', 'ADAUSDT', ...]
} catch (error) {
console.error('Failed to get cached symbols:', error.message);
}
`

$3

#### 3.1 Get 24hr Ticker (All Symbols)
Get 24-hour price change statistics for all symbols.

`javascript
try {
const ticker24hr = await sdk.getTicker24hr();
console.log('24hr Ticker (All):', ticker24hr);
// Output: [
// {
// symbol: 'BTCUSDT',
// priceChange: '1234.56',
// priceChangePercent: '2.5',
// weightedAvgPrice: '50000.00',
// prevClosePrice: '48765.44',
// lastPrice: '50000.00',
// volume: '1234.5678'
// }
// ]
} catch (error) {
console.error('Failed to get 24hr ticker:', error.message);
}
`

#### 3.2 Get 24hr Ticker (Specific Symbol)
Get 24-hour price change statistics for a specific symbol.

`javascript
try {
const btcTicker = await sdk.getTicker24hr('BTCUSDT');
console.log('BTC 24hr Ticker:', btcTicker);
// Output: {
// symbol: 'BTCUSDT',
// priceChange: '1234.56',
// priceChangePercent: '2.5',
// lastPrice: '50000.00',
// volume: '1234.5678'
// }
} catch (error) {
console.error('Failed to get BTC ticker:', error.message);
}
`

#### 3.3 Get Ticker Price (All Symbols)
Get current price for all symbols.

`javascript
try {
const allPrices = await sdk.getTickerPrice();
console.log('All Prices:', allPrices);
// Output: [
// { symbol: 'BTCUSDT', price: '50000.00' },
// { symbol: 'ETHUSDT', price: '3000.00' }
// ]
} catch (error) {
console.error('Failed to get all prices:', error.message);
}
`

#### 3.4 Get Ticker Price (Specific Symbol)
Get current price for a specific symbol.

`javascript
try {
const btcPrice = await sdk.getTickerPrice('BTCUSDT');
console.log('BTC Price:', btcPrice);
// Output: { symbol: 'BTCUSDT', price: '50000.00' }
} catch (error) {
console.error('Failed to get BTC price:', error.message);
}
`

$3

#### 4.1 Get Depth (Order Book)
Retrieve order book depth for a symbol with customizable limit.

`javascript
try {
// Get depth with 5 levels
const depth5 = await sdk.getDepth('BTCUSDT', 5);
console.log('Depth (5 levels):', depth5);
// Output: {
// lastUpdateId: 123456789,
// bids: [['50000.00', '1.234'], ['49999.00', '0.567']],
// asks: [['50001.00', '0.789'], ['50002.00', '1.123']]
// }

// Get depth with 20 levels
const depth20 = await sdk.getDepth('BTCUSDT', 20);
console.log('Depth (20 levels):', depth20);
} catch (error) {
console.error('Failed to get depth:', error.message);
}
`

#### 4.2 Clear Depth Cache
Clear cached depth data to get fresh order book information.

`javascript
try {
const clearResult = await sdk.clearDepthCache();
console.log('Cache cleared:', clearResult);
// Output: { success: true, message: 'Depth cache cleared' }
} catch (error) {
console.error('Failed to clear cache:', error.message);
}
`

$3

#### 5.1 Get Recent Trades
Retrieve recent trades for a symbol with customizable limit.

`javascript
try {
// Get 5 recent trades
const trades5 = await sdk.getTrades('BTCUSDT', 5);
console.log('Recent Trades (5):', trades5);
// Output: [
// {
// id: 123456,
// price: '50000.00',
// qty: '0.001',
// quoteQty: '50.00',
// time: 1755320793351,
// isBuyerMaker: false,
// isBestMatch: false
// }
// ]

// Get 10 recent trades
const trades10 = await sdk.getTrades('BTCUSDT', 10);
console.log('Recent Trades (10):', trades10);
} catch (error) {
console.error('Failed to get trades:', error.message);
}
`

$3

#### 6.1 Get Klines (Candlesticks)
Retrieve historical candlestick data for technical analysis.

`javascript
try {
// Get 1-minute klines (5 candles)
const klines1m = await sdk.getKlines('BTCUSDT', '1m', 5);
console.log('1m Klines:', klines1m);
// Output: [
// {
// openTime: 1755320760000,
// open: '50000.00',
// high: '50010.00',
// low: '49990.00',
// close: '50005.00',
// volume: '123.456',
// closeTime: 1755320819999
// }
// ]

// Get 1-hour klines (5 candles)
const klines1h = await sdk.getKlines('BTCUSDT', '1h', 5);
console.log('1h Klines:', klines1h);

// Get daily klines (5 candles)
const klines1d = await sdk.getKlines('BTCUSDT', '1d', 5);
console.log('1d Klines:', klines1d);
} catch (error) {
console.error('Failed to get klines:', error.message);
}
`

Available Intervals:
- 1m - 1 minute
- 3m - 3 minutes
- 5m - 5 minutes
- 15m - 15 minutes
- 30m - 30 minutes
- 1h - 1 hour
- 2h - 2 hours
- 4h - 4 hours
- 6h - 6 hours
- 8h - 8 hours
- 12h - 12 hours
- 1d - 1 day
- 3d - 3 days
- 1w - 1 week
- 1M - 1 month

$3

#### 7.1 Get Account Information
Retrieve comprehensive account information including balances and permissions.

`javascript
try {
const account = await sdk.getAccount();
console.log('Account Info:', account);
// Output: {
// makerCommission: 15,
// takerCommission: 15,
// buyerCommission: 0,
// sellerCommission: 0,
// canTrade: true,
// canWithdraw: true,
// canDeposit: true,
// updateTime: 0,
// accountType: 'SPOT',
// balances: [
// {
// asset: 'BTC',
// free: '1.00000000',
// locked: '0.00000000'
// }
// ]
// }
} catch (error) {
console.error('Failed to get account:', error.message);
}
`

#### 7.2 Get Account Balance
Get simplified balance information for all assets.

`javascript
try {
const balance = await sdk.getBalance();
console.log('Account Balance:', balance);
// Output: [
// {
// asset: 'BTC',
// free: '1.00000000',
// locked: '0.00000000',
// total: '1.00000000'
// }
// ]
} catch (error) {
console.error('Failed to get balance:', error.message);
}
`

#### 7.3 Get Account Status
Check account status and trading permissions.

`javascript
try {
const status = await sdk.getAccountStatus();
console.log('Account Status:', status);
// Output: {
// canTrade: true,
// canWithdraw: true,
// canDeposit: true,
// updateTime: 0
// }
} catch (error) {
console.error('Failed to get account status:', error.message);
}
`

#### 7.4 Get My Trades
Retrieve your trading history with optional filtering.

`javascript
try {
// Get all trades
const allTrades = await sdk.getMyTrades();
console.log('All My Trades:', allTrades);

// Get trades for specific symbol
const btcTrades = await sdk.getMyTrades({ symbol: 'BTCUSDT' });
console.log('BTC Trades:', btcTrades);

// Get trades with limit
const recentTrades = await sdk.getMyTrades({ limit: 10 });
console.log('Recent Trades:', recentTrades);

// Get trades with symbol and limit
const btcRecentTrades = await sdk.getMyTrades({
symbol: 'BTCUSDT',
limit: 5
});
console.log('BTC Recent Trades:', btcRecentTrades);
} catch (error) {
console.error('Failed to get my trades:', error.message);
}
`

$3

#### 8.1 Get API Keys
Retrieve all API keys associated with your account.

`javascript
try {
const apiKeys = await sdk.getApiKeys();
console.log('API Keys:', apiKeys);
// Output: [
// {
// id: 'key_id_123',
// name: 'Trading Bot Key',
// apiKey: 'ymta_...',
// permissions: { read: true, write: true },
// createdAt: '2025-08-16T05:00:00Z',
// lastUsed: '2025-08-16T05:30:00Z'
// }
// ]
} catch (error) {
console.error('Failed to get API keys:', error.message);
}
`

#### 8.2 Get Active API Keys
Get only active (non-revoked) API keys.

`javascript
try {
const activeKeys = await sdk.getActiveApiKeys();
console.log('Active API Keys:', activeKeys);
} catch (error) {
console.error('Failed to get active API keys:', error.message);
}
`

#### 8.3 Get API Key by Name
Find a specific API key by its name.

`javascript
try {
const keyByName = await sdk.getApiKeyByName('Trading Bot Key');
console.log('API Key by Name:', keyByName);
} catch (error) {
console.error('Failed to get API key by name:', error.message);
}
`

#### 8.4 Create API Key
Create a new API key with specific permissions.

`javascript
try {
const newKey = await sdk.createApiKey({
name: 'My Trading Bot',
userId: 'user_123',
permissions: {
read: true,
write: true,
trading: true
}
});
console.log('New API Key:', newKey);
// Output: {
// id: 'new_key_id',
// name: 'My Trading Bot',
// apiKey: 'ymta_new_api_key_...',
// secretKey: 'new_secret_key_...',
// permissions: { read: true, write: true, trading: true }
// }
} catch (error) {
console.error('Failed to create API key:', error.message);
}
`

#### 8.5 Revoke API Key
Revoke (delete) an existing API key.

`javascript
try {
const revokeResult = await sdk.revokeApiKey('key_id_123');
console.log('API Key Revoked:', revokeResult);
// Output: { success: true, message: 'API key revoked successfully' }
} catch (error) {
console.error('Failed to revoke API key:', error.message);
}
`

#### 8.6 Update API Key Permissions
Modify permissions for an existing API key.

`javascript
try {
const updateResult = await sdk.updateApiKeyPermissions('key_id_123', {
read: true,
write: false,
trading: true
});
console.log('Permissions Updated:', updateResult);
} catch (error) {
console.error('Failed to update permissions:', error.message);
}
`

#### 8.7 Get API Key Statistics
Get usage statistics for an API key.

`javascript
try {
const stats = await sdk.getApiKeyStats('key_id_123');
console.log('API Key Stats:', stats);
// Output: {
// totalRequests: 1500,
// successfulRequests: 1480,
// failedRequests: 20,
// lastUsed: '2025-08-16T05:30:00Z',
// createdAt: '2025-08-16T05:00:00Z'
// }
} catch (error) {
console.error('Failed to get API key stats:', error.message);
}
`

🔄 WebSocket Support

$3

`javascript
import { YamataAdapterSDK } from 'yamata-adapter-sdk';

const sdk = new YamataAdapterSDK({
apiKey: 'ymta_your_api_key',
secretKey: 'your_secret_key',
baseUrl: 'http://localhost:3080'
});

// Connect to WebSocket
await sdk.connectWebSocket();

// Subscribe to real-time data
sdk.subscribeToTicker('BTCUSDT', (data) => {
console.log('Real-time BTC price:', data.price);
});

sdk.subscribeToDepth('BTCUSDT', (data) => {
console.log('Real-time order book:', data);
});

sdk.subscribeToTrades('BTCUSDT', (data) => {
console.log('Real-time trades:', data);
});

// Unsubscribe when done
sdk.unsubscribeFromTicker('BTCUSDT');
sdk.disconnectWebSocket();
`

🛠️ Error Handling

$3

`javascript
try {
const result = await sdk.getAccount();
console.log('Success:', result);
} catch (error) {
switch (error.code) {
case 'AUTH_ERROR':
console.error('Authentication failed:', error.message);
break;
case 'RATE_LIMIT':
console.error('Rate limit exceeded:', error.message);
break;
case 'INVALID_PARAMETER':
console.error('Invalid parameter:', error.message);
break;
case 'NETWORK_ERROR':
console.error('Network error:', error.message);
break;
default:
console.error('Unexpected error:', error.message);
}

// Access detailed error information
console.log('Error details:', {
status: error.status,
code: error.code,
timestamp: error.timestamp,
details: error.details
});
}
`

$3

- AuthenticationError: Invalid API key, signature, or timestamp
- RateLimitError: Too many requests
- ValidationError: Invalid parameters
- NetworkError: Connection issues
- ServerError: Server-side errors

📊 Testing

$3

`bash


Test all public endpoints

npm run test:public

Or run directly

node test-all-get-apis.js
`

$3

`bash


Test all authenticated endpoints (requires valid API keys)

npm run test:auth

Or run directly

node test-authenticated-apis.js
`

$3

`bash


Test basic SDK functions


node test-sdk-functions.js
`

📖 Examples

$3

`bash


Run basic usage example

npm run example

Or run directly

node examples/basic-usage.js
`

$3

`bash


Run comprehensive GET APIs example

npm run example:get-apis

Or run directly

node examples/get-apis-example.js
`

$3

`bash


Run WebSocket example


node examples/websocket-example.js
`

$3

- examples/basic-usage.js - Basic SDK functionality demonstration
- examples/get-apis-example.js - Comprehensive GET APIs testing and demonstration
- examples/websocket-example.js - Real-time WebSocket data streaming

🔧 Configuration Options

$3

`javascript
const config = {
// Required
apiKey: 'ymta_your_api_key',
secretKey: 'your_secret_key',
baseUrl: 'http://localhost:3080',

// Optional
debug: false, // Enable debug logging
timeout: 30000, // Request timeout (ms)
recvWindow: 5000, // Receive window (ms)
retries: 3, // Number of retries
retryDelay: 1000, // Delay between retries (ms)
userAgent: 'YamataSDK/1.0.0' // Custom user agent
};
`

$3

`bash


Required

export YAMATA_API_KEY="ymta_your_api_key"
export YAMATA_SECRET_KEY="your_secret_key"
export YAMATA_BASE_URL="http://localhost:3080"

Optional

export YAMATA_DEBUG="true"
export YAMATA_TIMEOUT="30000"
export YAMATA_RECV_WINDOW="5000"
export YAMATA_TEST_USER_ID="your_test_user_id"
`

🚀 Performance Optimization

$3

1. Reuse SDK Instance: Create one SDK instance and reuse it
2. Batch Requests: Group related requests when possible
3. Use WebSocket: For real-time data instead of polling
4. Implement Caching: Cache frequently accessed data
5. Handle Rate Limits: Implement exponential backoff

$3

`javascript
import { YamataAdapterSDK } from 'yamata-adapter-sdk';

class TradingBot {
constructor() {
this.sdk = new YamataAdapterSDK({
apiKey: process.env.YAMATA_API_KEY,
secretKey: process.env.YAMATA_SECRET_KEY,
baseUrl: process.env.YAMATA_BASE_URL,
debug: process.env.NODE_ENV === 'development'
});

this.cache = new Map();
this.cacheTimeout = 5000; // 5 seconds
}

async getCachedPrice(symbol) {
const cacheKey = price_${symbol};
const cached = this.cache.get(cacheKey);

if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
return cached.data;
}

const price = await this.sdk.getTickerPrice(symbol);
this.cache.set(cacheKey, {
data: price,
timestamp: Date.now()
});

return price;
}

async monitorPrices(symbols) {
await this.sdk.connectWebSocket();

symbols.forEach(symbol => {
this.sdk.subscribeToTicker(symbol, (data) => {
console.log(${symbol} price: ${data.price});
this.cache.set(price_${symbol}, {
data: { symbol, price: data.price },
timestamp: Date.now()
});
});
});
}
}
`

📝 API Key Format & Security

$3

- Prefix: Must start with ymta_
- Length: Minimum 32 characters
- Format: Alphanumeric with underscores
- Example: ymta_trading_bot_key_1234567890abcdef`

$3

1. Never expose secret keys in client-side code
2. Use environment variables for sensitive data
3. Implement proper key rotation
4. Monitor API key usage regularly
5. Use minimal permissions for each key

---

Made with ❤️ by the Yamata Team