TypeScript

Get Started

The Upbit SDK is an official SDK library that allows you to use Upbit APIs (REST API, WebSocket) in various programming languages. It includes type definitions for all request parameters and responses, enabling auto-completion and type checking during development. You can conveniently integrate the API with minimal code without having to implement authentication, HTTP requests, or error handling yourself.

This guide explains how to call the Upbit API using the Upbit SDK library in a TypeScript environment.

Upbit SDK Documentation

The Upbit TypeScript SDK provides official documentation. Click the link below to visit the official website.

• Getting Started Guide — Installation and basic usage of the Upbit TypeScript SDK
• Upbit SDK API Reference — Full list of APIs supported by the SDK
• SDK Example Code — Sample Code and Detailed Usage

TypeScript Integration Guide

• Minimum Version: TypeScript 4.9 or later
• Node.js 22 LTS or later recommended

Initialize the Project and Install the SDK

TypeScript recommends setting up a project-specific environment. Create a project and install the SDK as follows.

1. Create a Project Directory

mkdir upbit_sdk_project
cd upbit_sdk_project

npm init -y

2. Install TypeScript and the SDK

npm install @upbit-official/upbit-sdk
npm install -D typescript ts-node @types/node

3. Create a TypeScript Configuration File

npx tsc --init

Client Instance Setup

The Upbit SDK is designed to maintain state, including authentication information and environment configuration. Therefore, it is common to create and use a client instance as shown below.

Authentication via Environment Variables: If you set the UPBIT_ACCESS_KEY and UPBIT_SECRET_KEYenvironment variables, the client will automatically read the authentication credentials without requiring you to pass the keys directly when creating the client. It is not recommended to include API keys directly in the source code for security reasons; use environment variables or a .env file instead.

import Upbit from '@upbit-official/upbit-sdk';

const client = new Upbit({
  accessKey: process.env['UPBIT_ACCESS_KEY'],
  secretKey: process.env['UPBIT_SECRET_KEY'],
  environment: 'sg',
// environment: 'sg' | 'id' | 'th'
});

You can check the Upbit APIs available through the Upbit SDK by clicking the link below.

• Upbit SDK API Reference: https://github.com/upbit-official/upbit-sdk-typescript/blob/main/api.md

Confirm Instance Configuration

To verify that the instance is properly configured, write and run the code as follows. If it is configured correctly, the API response will be returned; otherwise, an error will be returned.

API Calls Requiring Authentication

import Upbit from '@upbit-official/upbit-sdk';

async function getBalance(): Promise<void> {
  const client = new Upbit({
    accessKey: process.env['UPBIT_ACCESS_KEY'],
    secretKey: process.env['UPBIT_SECRET_KEY'],
    environment: 'sg',
  });
  const result = await client.accounts.list();
  console.log(result);
}

async function main(): Promise<void> {
  await getBalance();
}

main().catch(console.error);

API Calls Without Authentication

import Upbit from '@upbit-official/upbit-sdk';

async function listTradingPairsDefault(): Promise<void> {
  const client = new Upbit({
    environment: 'sg', // environment: 'sg' | 'id' | 'th'
  });

  const result = await client.tradingPairs.list({
    is_details: false, // Exclude detailed information
  });

  console.log(result);
}

async function main(): Promise<void> {
  await listTradingPairsDefault();
}

main().catch(console.error);

Error Handling

Errors such as authentication failures or rate limit exceedance may occur when calling the API. You can handle exceptions as follows.

const accounts = await client.accounts.list().catch(async (err) => {
  if (err instanceof Upbit.APIError) {
    console.log(err.status);  // 404
    console.log(err.name);    // "not_found"  (Upbit API error name, or null)
    console.log(err.message); // "404 [not_found] no Route matched"
    console.log(err.headers); // {server: 'nginx', ...}
  } else {
    throw err;
  }
});

Error Types

Additional Features

Retry Configuration

For certain errors, automatic retries are performed up to a maximum of two times by default.

// Set default options for all requests:
const client = new Upbit({
  maxRetries: 0, // Default is 2
});

// Or set options per request:
await client.accounts.list({
  maxRetries: 5,
});

Timeout Configuration

The default timeout is 60 seconds and can be changed as follows.

// Set default options for all requests:
const client = new Upbit({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Set options per request:
await client.accounts.list({
  timeout: 5 * 1000,
});

Auto-pagination

Upbit API’s list retrieval methods support pagination. By using thefor await ... ofsyntax, you can iterate through items across all pages.

async function fetchAllOrders(params) {
  const allOrders = [];
  // Automatically fetches the next page as needed.
  for await (const order of client.orders.listOpen()) {
    allOrders.push(order);
  }
  return allOrders;
}

You can also request one page at a time.

let page = await client.orders.listOpen();

for (const order of page.items) {
  console.log(order);
}

// Convenience methods for manual pagination:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}