Development Environment Setup

Get Started

Before integrating with the Upbit API, set up your development environment based on your preferred programming language. Follow the setup instructions for your OS to get started with Python, Java, or Node.js.

Check the proper endpoint based on your region.

The examples in this page is written using Singapore fiat code(SGD). Set the quote currency to match your region. The base_url differs by country/region. Make sure to specify the correct region value for your environment.

- Singapore (sg): https://sg-api.upbit.com
- Indonesia (id): https://id-api.upbit.com
- Thailand (th): https://th-api.upbit.com

Python

macOS Setup

To install Python on macOS, use Homebrew, the popular package manager for Mac.

1. Install Homebrew

Open your terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Verify Homebrew is installed correctly:

brew -v

Homebrew 4.6.1

2. Python Installation

Install Python using Homebrew:

brew install python

Check your Python version:

python3 --version

Python 3.13.2

3. Set Up a Virtual Environment

Using a virtual environment keeps your project dependencies isolated.

python3 -m venv .venv

source .venv/bin/activate

If activated, your terminal prompt will show the environment name:

(.venv) user@computer:~/project$

Within a virtual environment, you can freely install the packages required for your development setup. The packages installed in this way do not affect the global environment, making it easy to manage dependencies for each project independently.

To deactivate:

deactivate

Windows Setup

1. Download Python Installer

Go to the official Python downloads page and download the latest installer. During installation, check the Add Python to PATH option to use Python from the command line.

Go to Python Download

2. Set Up a Virtual Environment

Python uses virtual environments to prevent conflicts between projects and manage dependencies. After installing Python, you can create and activate a virtual environment by running the following commands in your terminal.

python -m venv .venv

.venv\Scripts\activate

To deactivate:

deactivate

HTTP Client Library Guide

Here are the recommended libraries for calling REST APIs and WebSocket endpoints.

REST API – `requests` library

1. Installation

pip install requests

2. Basic Usage

import requests

url = "https://{region}-api.upbit.com/v1/ticker?markets={fiat}-BTC"
response = requests.get(url)
data = response.json()
print(data[0]["trade_price"])

You can easily send various HTTP requests such as GET and POST, etc

WebSockets - `websocket-client`, `websockets` Library

These are libraries for synchronous and asynchronous WebSocket connections, respectively. You can choose and use the one that best fits your development environment.

1. Installation

pip install websocket-client
pip install websockets

2. Basic Usage

import websocket
import json

def on_message(ws, message):
    print("Received:", message)

ws = websocket.WebSocketApp(
    "wss://{region}-api.upbit.com/websocket/v1",
    on_message=on_message
)

# Subscription message (for ticker stream)
subscribe_message = [
    {"ticket": "test"},
    {"type": "ticker", "codes": ["SGD-BTC"]}
]

def on_open(ws):
    ws.send(json.dumps(subscribe_message))

ws.on_open = on_open
ws.run_forever(ping_interval=30, ping_timeout=10, reconnect=2)

Use callback functions (on_message) to handle incoming messages.
You can implement on_open, on_close, and on_error to manage connection state:
- on_open: Send subscription messages or initialize on connection.
- on_close: Handle cleanup or reconnect logic.
- on_error: Handle exceptions and errors.
For private WebSocket APIs, include your auth token in the headers. See the recipe below.

[Python] Websocket Connection

Open Recipe

Java

Setting Up IntelliJ IDEA

IntelliJ IDEA is a widely used IDE for Java/Kotlin development, available in free Community and paid Ultimate versions.

1. Install IntelliJ IDEA

You can install IntelliJ IDEA from the official JetBrains website. JetBrains offers two editions of IntelliJ IDEA: Community Edition (free) and Ultimate (paid). Choose the edition that best fits your needs and install it.

Go to IntelliJ IDEA

2. JDK Installation

Download an OpenJDK distribution (e.g., Amazon, IBM, Microsoft) and install it.

3. Configure JDK in IntelliJ

Launch IntelliJ and open or create a project.
Go to File > Project Structure.
Under Platform Settings > SDKs, add your JDK if not detected.
If the installed JDK is not listed, click the + button at the top and then select Add JDK.
Choose the JDK installation path. Common JDK installation paths by operating system are:
- macOS: /Library/Java/JavaVirtualMachines/<jdk-version>/Contents/Home
- Windows: C:\Program Files\Java\<jdk-version>
Once you select the correct path, IntelliJ IDEA will automatically detect and add the JDK.
In the Project Structure window, select Project from the left-hand menu.
From the Project SDK dropdown menu on the right, choose the JDK you added.
Set the Language level to the Java version appropriate for your project.
After making the changes, click OK or Apply in the lower right corner to save the settings and close the window.

4. Test Your Java Setup

To verify your JDK setup, create a simple Java class and run it for testing.

public class Main {
    public static void main(String[] args) {
        System.out.println("Hello, Java!");
    }
}

If you see "Hello, Java!", your setup is correct.

Hello, Java!

HTTP Client Library Guide

Here are some commonly used HTTP client libraries in Java for calling REST APIs and WebSockets. Choose the one that best fits your development environment and framework.

Features and installation methods for each library

1. OkHttp

A widely used Java/Android HTTP client supporting both REST and WebSocket. Lightweight, supports sync/async, and is highly customizable.

implementation 'com.squareup.okhttp3:okhttp:{version}'

<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
  <version>{version}</version>
</dependency>

Examples of REST API calls and WebSocket connections are shown below.

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
    .url("https://{region}-api.upbit.com/v1/ticker?markets={fiat}-BTC")
    .addHeader("accept", "application/json")
    .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}

import okhttp3.*;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
    .url("wss://sg-api.upbit.com/websocket/v1")
    .build();

WebSocketListener listener = new WebSocketListener() {
    @Override
    public void onOpen(WebSocket webSocket, Response response) {
        String subscribeMessage = "[{\"ticket\":\"test\"},{\"type\":\"ticker\",\"codes\":[\"SGD-BTC\"]}]";
        webSocket.send(subscribeMessage);
    }
    @Override
    public void onMessage(WebSocket webSocket, String text) {
        System.out.println("Received: " + text);
    }
    @Override
    public void onClosed(WebSocket webSocket, int code, String reason) {
        System.out.println("Closed: " + reason);
    }
    @Override
    public void onFailure(WebSocket webSocket, Throwable t, Response response) {
        t.printStackTrace();
    }
};
client.newWebSocket(request, listener);
client.dispatcher().executorService().shutdown();

2. Spring WebClient

A reactive HTTP/WebSocket client available since Spring 5, well-suited for high-performance or streaming use cases.

implementation 'org.springframework.boot:spring-boot-starter-webflux'

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

Examples of REST API calls and WebSocket connections are shown below.

import org.springframework.web.reactive.function.client.WebClient;

WebClient client = WebClient.create();
String response = client.get()
    .uri("https://{region}-api.upbit.com/v1/ticker?markets={fiat}-BTC")
    .header("accept", "application/json")
    .retrieve()
    .bodyToMono(String.class)
    .block();
System.out.println(response);

import org.springframework.web.reactive.socket.client.ReactorNettyWebSocketClient;
import org.springframework.web.reactive.socket.WebSocketHandler;
import org.springframework.web.reactive.socket.WebSocketSession;
import reactor.core.publisher.Mono;

import java.net.URI;

ReactorNettyWebSocketClient client = new ReactorNettyWebSocketClient();
client.execute(
    URI.create("wss://sg-api.upbit.com/websocket/v1"),
    session -> session.send(
            Mono.just(session.textMessage(
                    "[{\"ticket\":\"test\"},{\"type\":\"ticker\",\"codes\":[\"SGD-BTC\"]}]"
            ))
        ).thenMany(session.receive()
            .map(msg -> {
                System.out.println("Received: " + msg.getPayloadAsText());
                return msg;
            })
        ).then()
).block();

3. Retrofit

A REST client built on OkHttp. Define API endpoints via interfaces for clean and type-safe code. (For WebSocket, use OkHttp directly.)

implementation 'com.squareup.retrofit2:retrofit:2.11.0'
implementation 'com.squareup.retrofit2:converter-gson:2.11.0'

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>2.11.0</version>
</dependency>
<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>converter-gson</artifactId>
  <version>2.11.0</version>
</dependency>

An example of a REST API call is shown below.

import retrofit2.Call;
import retrofit2.Retrofit;
import retrofit2.converter.gson.GsonConverterFactory;
import retrofit2.http.GET;
import retrofit2.http.Query;
import retrofit2.http.Headers;

import java.util.List;
import java.util.Map;

public interface UpbitService {
    @GET("v1/ticker")
    @Headers("accept: application/json")
    Call<List<Map<String, Object>>> getTicker(@Query("markets") String markets);
}

// Usage
Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://{region}-api.upbit.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build();

UpbitService service = retrofit.create(UpbitService.class);
Call<List<Map<String, Object>>> call = service.getTicker("SGD-BTC");
List<Map<String, Object>> response = call.execute().body();
System.out.println(response);

4. Java Standard HttpClient (Java 11+)

Native HTTP client in Java 11+, supports HTTP/2 and async, with built-in WebSocket support.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://{region}-api.upbit.com/v1/ticker?markets={fiat}-BTC"))
    .header("accept", "application/json")
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.WebSocket;
import java.util.concurrent.CompletionStage;

HttpClient client = HttpClient.newHttpClient();
WebSocket webSocket = client.newWebSocketBuilder()
    .buildAsync(URI.create("wss://sg-api.upbit.com/websocket/v1"), new WebSocket.Listener() {
        @Override
        public void onOpen(WebSocket webSocket) {
            String subscribeMessage = "[{\"ticket\":\"test\"},{\"type\":\"ticker\",\"codes\":[\"SGD-BTC\"]}]";
            webSocket.sendText(subscribeMessage, true);
            WebSocket.Listener.super.onOpen(webSocket);
        }
        @Override
        public CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last) {
            System.out.println("Received: " + data);
            return WebSocket.Listener.super.onText(webSocket, data, last);
        }
        @Override
        public void onError(WebSocket webSocket, Throwable error) {
            error.printStackTrace();
        }
    }).join();

[Java] Connect Websocket

Open Recipe

Node.js

macOS Setup

To install Node.js on macOS, use Homebrew, the popular package manager for Mac.

1. Homebrew Installation

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After completing the installation, run the following command in the terminal to check the Homebrew version. If the installation was successful, the version information for Homebrew will be displayed.

brew -v

Homebrew 4.5.3

2. NVM Installation

brew install nvm

After installing NVM, add the environment variables to your shell profile by running the following command in the terminal.

For zsh Users

echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$(brew --prefix nvm)/nvm.sh" ] && source "$(brew --prefix nvm)/nvm.sh"' >> ~/.zshrc

For base Users

echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bash_profile
echo '[ -s "$(brew --prefix nvm)/nvm.sh" ] && source "$(brew --prefix nvm)/nvm.sh"' >> ~/.bash_profile

Update your shell profile and run the following command in the terminal to apply the changes.

For zsh Users

source ~/.zshrc

For base Users

source ~/.bash_profile

After applying the settings, run the following command in the terminal to check the NVM version. If the installation was successful, the NVM version will be displayed.

nvm --version

0.40.1

3. Node.js Installation

nvm install <version>

nvm install --lts

After installing Node.js, run the following command in the terminal to check the Node.js version. If the installation was successful, the Node.js version will be displayed.

node -v

v22.14.0

Windows Setup

1. Download Node.js Installer

Go to the Node.js official downloads page and download the latest Windows installer. The Add to PATH option is checked by default; you can use Node.js from the terminal after installation.

Go to Node.js Download

After installing Node.js, run the following command in the terminal to check the Node.js version. If the installation was successful, the Node.js version will be displayed.

node -v

v22.14.0

HTTP Client Library Guide

Recommended libraries for REST API and WebSocket integration in Node.js:

REST API – `Axios` library

Axios is the most popular Promise-based HTTP client for Node.js (and browsers).

npm install axios

An example of a REST API call is shown below:

const axios = require('axios');

axios.get('https://{region}-api.upbit.com/v1/ticker', {
  params: { markets: 'SGD-BTC' },
  headers: { 'accept': 'application/json' }
})
.then(response => {
  console.log(response.data[0].trade_price);
})
.catch(error => {
  console.error(error);
});

WebSocket – `ws` library

ws is the most widely used WebSocket client/server library for Node.js.

npm install ws

Example:

const WebSocket = require('ws');

const ws = new WebSocket('wss://{region}-api.upbit.com/websocket/v1', {
  headers: {
    'accept': 'application/json'
  }
});

ws.on('open', () => {
  const subscribeMessage = [
    { ticket: 'test' },
    { type: 'ticker', codes: ['{fiat}-BTC'] }
  ];
  ws.send(JSON.stringify(subscribeMessage));
});

ws.on('message', (data) => {
  console.log('Received:', data.toString());
});

ws.on('close', () => {
  console.log('WebSocket connection closed');
});

ws.on('error', (error) => {
  console.error('WebSocket error:', error);
});

[Node.js] Connect Websocket

Open Recipe

Get Started

Python

macOS Setup

1. Install Homebrew

2. Python Installation

3. Set Up a Virtual Environment

Windows Setup

1. Download Python Installer

2. Set Up a Virtual Environment

HTTP Client Library Guide

REST API – requests library

1. Installation

2. Basic Usage

WebSockets - websocket-client, websockets Library

1. Installation

2. Basic Usage

Java

Setting Up IntelliJ IDEA

1. Install IntelliJ IDEA

2. JDK Installation

3. Configure JDK in IntelliJ

4. Test Your Java Setup

HTTP Client Library Guide

1. OkHttp

2. Spring WebClient

3. Retrofit

4. Java Standard HttpClient (Java 11+)

Node.js

macOS Setup

1. Homebrew Installation

2. NVM Installation

3. Node.js Installation

Windows Setup

1. Download Node.js Installer

HTTP Client Library Guide

REST API – Axios library

WebSocket – ws library

REST API – `requests` library

WebSockets - `websocket-client`, `websockets` Library

REST API – `Axios` library

WebSocket – `ws` library