TradeWatch.io Java SDK

Official SDK for the TradeWatch.io API.

Other SDKs

What is TradeWatch.io?

TradeWatch.io is a market data platform and API for real-time and historical prices across crypto, stocks, indices, currencies, and commodities.

Try the Interactive API Playground

Want to test endpoints without writing code first? Use the TradeWatch Interactive API Playground to run requests directly in your browser.

Resources

• REST API reference: https://tradewatch.io/docs/api-reference/introduction
• WebSocket API reference: https://tradewatch.io/docs/websocket-api/introduction
• Support channels: https://tradewatch.io/docs/platform/support

Quick Start

1. Create an API key in the TradeWatch Dashboard.
2. Follow platform setup docs: Getting started.

Table of Contents

• Documentation
• Reference
• Usage
• Environments
• Base Url
• Exception Handling
• Advanced
  • Custom Client
  • Retries
  • Timeouts
  • Custom Headers
  • Access Raw Response Data

Documentation

API reference documentation is available here.

Reference

A full reference for this library is available here.

Usage

Instantiate and use the client with the following:

package com.example.usage;

import io.tradewatch.client.TradewatchApiClient;
import io.tradewatch.client.resources.crypto.requests.CryptoGetQuoteRequest;

public class Example {
    public static void main(String[] args) {
        TradewatchApiClient client = TradewatchApiClient
            .builder()
            .apiKey("<value>")
            .build();

        client.crypto().getQuote(
            CryptoGetQuoteRequest
                .builder()
                .symbol("BTC-USD")
                .precision(2)
                .build()
        );
    }
}

Environments

This SDK allows you to configure different environments for API requests.

import io.tradewatch.client.TradewatchApiClient;
import io.tradewatch.client.core.Environment;

TradewatchApiClient client = TradewatchApiClient
    .builder()
    .environment(Environment.Default)
    .build();

Base Url

You can set a custom base URL when constructing the client.

import io.tradewatch.client.TradewatchApiClient;

TradewatchApiClient client = TradewatchApiClient
    .builder()
    .url("https://example.com")
    .build();

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), an API exception will be thrown.

import io.tradewatch.client.core.TradewatchApiApiException;

try{
    client.crypto().getQuote(...);
} catch (TradewatchApiApiException e){
    // Do something with the API exception...
}

Advanced

Custom Client

This SDK is built to work with any instance of OkHttpClient. By default, if no client is provided, the SDK will construct one. However, you can pass your own client like so:

import io.tradewatch.client.TradewatchApiClient;
import okhttp3.OkHttpClient;

OkHttpClient customClient = ...;

TradewatchApiClient client = TradewatchApiClient
    .builder()
    .httpClient(customClient)
    .build();

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). Before defaulting to exponential backoff, the SDK will first attempt to respect the Retry-After header (as either in seconds or as an HTTP date), and then the X-RateLimit-Reset header (as a Unix timestamp in epoch seconds); failing both of those, it will fall back to exponential backoff.

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the maxRetries client option to configure this behavior.

import io.tradewatch.client.TradewatchApiClient;

TradewatchApiClient client = TradewatchApiClient
    .builder()
    .maxRetries(1)
    .build();

Timeouts

The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.

import io.tradewatch.client.TradewatchApiClient;
import io.tradewatch.client.core.RequestOptions;

// Client level
TradewatchApiClient client = TradewatchApiClient
    .builder()
    .timeout(60)
    .build();

// Request level
client.crypto().getQuote(
    ...,
    RequestOptions
        .builder()
        .timeout(60)
        .build()
);

Custom Headers

The SDK allows you to add custom headers to requests. You can configure headers at the client level or at the request level.

import io.tradewatch.client.TradewatchApiClient;
import io.tradewatch.client.core.RequestOptions;

// Client level
TradewatchApiClient client = TradewatchApiClient
    .builder()
    .addHeader("X-Custom-Header", "custom-value")
    .addHeader("X-Request-Id", "abc-123")
    .build();
;

// Request level
client.crypto().getQuote(
    ...,
    RequestOptions
        .builder()
        .addHeader("X-Request-Header", "request-value")
        .build()
);

Access Raw Response Data

The SDK provides access to raw response data, including headers, through the withRawResponse() method. The withRawResponse() method returns a raw client that wraps all responses with body() and headers() methods. (A normal client's response is identical to a raw client's response.body().)

GetQuoteHttpResponse response = client.crypto().withRawResponse().getQuote(...);

System.out.println(response.body());
System.out.println(response.headers().get("X-My-Header"));

Available Methods

account

Method	Required Params	Summary	Description
getUsage()	-	Usage statistics	Get the usage statistics of your API account

currencies

Method	Required Params	Summary	Description
convert(from, to)	from, to	Conversion	Convert one symbol to another
getInsights()	-	Get Insights	Get recent currencies insights.
getQuote(symbol)	symbol	Last Quote	Get the last quote tick for the provided symbol.
getQuotes(symbols)	symbols	Last Quotes	Get the last quote tick for the provided symbols.
getSymbols()	-	Available Symbols	Get list of available symbols

crypto

Method	Required Params	Summary	Description
convert(from, to)	from, to	Conversion	Convert one symbol to another
getExchanges()	-	Available Exchanges	Get list of available cryptocurrency exchanges
getInsights()	-	Get Insights	Get recent crypto insights.
getQuote(symbol)	symbol	Last Quote	Get the last quote tick for the provided symbol.
getQuotes(symbols)	symbols	Last Quotes	Get the last quote tick for the provided symbols.
getSymbols()	-	Available Symbols	Get list of available symbols

indices

Method	Required Params	Summary	Description
getInsights()	-	Get Insights	Get recent indices insights.
getQuote(symbol)	symbol	Last Quote	Get the last quote tick for the provided symbol.
getQuotes(symbols)	symbols	Last Quotes	Get the last quote tick for the provided symbols.
getSymbols()	-	Available Symbols	Get list of available symbols

stocks

Method	Required Params	Summary	Description
getHistoricalOhlc(symbol, resolution, start, end)	symbol, resolution, start, end	Get Historical Ohlc	Get historical OHLC candles for a symbol in a selected resolution and time range.
getHistoricalTicks(symbol, start, end)	symbol, start, end	Get Historical Ticks	Get raw historical ticks for a symbol in a selected time range using cursor pagination.
getInsights()	-	Get Insights	Get recent stocks insights.
getMarketHolidays(start, end)	start, end	Get Market Holidays	Get market holidays. It takes half-days into account.
getMarketStatus()	-	Get Market Status	Get the current status (open or closed) of a market. It takes holidays and half-days into account but does not factor in circuit breakers or halts.
getMarkets()	-	Get Markets	Get details about the markets available in this API.
getQuote(symbol)	symbol	Last Quote	Get the last quote tick for the provided symbol.
getQuotes(symbols)	symbols	Last Quotes	Get the last quote tick for the provided symbols.
getStockData(symbol)	symbol	Get Stock Data	Get Stock Data
getSymbols()	-	Available Symbols	Get list of available symbols
getTradingHours(start, end)	start, end	Get Trading Hours	Get trading hours. It takes half-days into account.
stockGetCountries()	-	Available Countries	Get list of available countries

commodities

Method	Required Params	Summary	Description
getInsights()	-	Get Insights	Get recent commodities insights.
getQuote(symbol)	symbol	Last Quote	Get the last quote tick for the provided symbol.
getQuotes(symbols)	symbols	Last Quotes	Get the last quote tick for the provided symbols.
getSymbols()	-	Available Symbols	Get list of available symbols
getTypes()	-	Available Types	Get list of available commodity types