NAV
python go javascript java

Introduction

Welcome to the Giottus API!

The base URL for all API calls is https://api.giottus.com.

Giottus APIs let you fetch data related to markets, tickers, trades, order books, fees, user balances, and transaction history (crypto and fiat deposits/withdrawals, open orders, trade history, etc.), and they also expose authenticated endpoints to place, cancel, and monitor spot orders.

Setup

Getting Started with the Giottus API

Before you can make authenticated requests, a few setup steps are required:

  1. Create an API Key

Visit the Giottus API Management page to generate a new API key. Each key provides:

  1. Synchronize Your Clock All private endpoints require a valid timestamp parameter. Requests are only accepted if the client’s clock is within a short window of the server time (default: 5 seconds, maximum: 60 seconds).

  2. Use HTTPS All requests must be made over HTTPS. API documentation shows relative paths — prepend them with the base URL (https://api.giottus.com).

  3. Generate Signatures For private requests, you must sign the request with your API secret using HMAC SHA-256. Most HTTP client libraries support this out of the box. Code samples are provided in the documentation to help you generate signatures correctly.

API Rate Limits

To ensure fair usage and platform stability, all Giottus API endpoints are rate-limited.

When rate limiting applies to a request, the response includes the following headers:

Header Description
X-RateLimit-Limit Maximum number of requests allowed in the current window.
X-RateLimit-Remaining Number of requests left before throttling occurs.
X-RateLimit-Reset UNIX timestamp (in seconds) when the current window resets.
Retry-After Returned with HTTP 429 responses; tells you how many seconds to wait before retrying.

If you exceed the allowed rate, the API will return error code -1003 (TOO_MANY_REQUESTS).

Public endpoints

Ticker

Sample response

[
  {
    "symbol": "BTC/USDT",
    "lastPrice": "26842.50",
    "high": "27100.00",
    "low": "26550.00",
    "volume": "123.4567",
    "change_24h": "-0.511",
    "time": "1706601123456"
  },
  {
    "symbol": "ETH/USDT",
    "lastPrice": "1720.40",
    "high": "1758.00",
    "low": "1682.90",
    "volume": "987.6543",
    "change_24h": "3.511",
    "time": "1706601123456"
  }
]

Returns the latest ticker snapshot for a single symbol or for all listed symbols.

Query Parameters

Parameter Type Required Description
symbol string No Trading symbol such as BTC/USDT. When omitted the route returns an array with all tickers.

Response Fields

Field Type Description
symbol string Trading symbol in uppercase.
lastPrice string Last traded price for the symbol.
high string Highest traded price in the rolling window tracked by Giottus API.
low string Lowest traded price in the rolling window.
volume string Total traded quantity during the window.
change_24h string This indicates a percentage change in price during the 24-hour period.
time string Execution time in milliseconds.

Symbols

Sample response

[
  "BTC/USDT",
  "ETH/USDT",
  "SHIB/USDT"
]

Returns the list of trading symbols available on the exchange in BASE/QUOTE format.

This endpoint does not accept query parameters.

Recent trades

Sample response

[
  {
    "price": "26840.10",
    "qty": "0.005",
    "quoteQty": "134.2005",
    "time": 1706601123456,
    "isBuyerMaker": false
  },
  {
    "price": "26838.90",
    "qty": "0.015",
    "quoteQty": "402.5835",
    "time": 1706601119789,
    "isBuyerMaker": true
  }
]

Fetches the most recent public trades for a trading pair.

Query Parameters

Parameter Type Required Description
symbol string Yes Trading symbol such as BTC/USDT (uppercase).
limit integer No Maximum number of trades to return (default 20, max 50).

Response Fields

Field Type Description
price string Executed price.
qty string Base asset quantity traded.
quoteQty string Quote asset amount (if available).
time number Execution time in milliseconds since epoch.
isBuyerMaker boolean true if the buyer was the maker side of the trade.

Order book

Sample response

{
  "bids": [
    ["26840.00", "0.532"],
    ["26839.50", "0.127"]
  ],
  "asks": [
    ["26841.00", "0.418"],
    ["26841.20", "0.296"]
  ]
}

Returns aggregated bid and ask levels for a symbol.

Query Parameters

Parameter Type Required Description
symbol string Yes Trading symbol such as BTC/USDT (uppercase).
limit integer No Maximum number of price levels per side (default 20, max 50).

Response Fields

Field Type Description
bids array Array of [price, quantity] levels sorted from highest to lowest price.
asks array Array of [price, quantity] levels sorted from lowest to highest price.

Assets

Sample response

[
  {
    "asset": "BTC",
    "name": "Bitcoin",
    "status": "ACTIVE",
    "networks": [
      {
        "name": "BTC",
        "deposit": {
          "min": "0.0005",
          "confirmations": 2,
          "enabled": true
        },
        "withdraw": {
          "min": "0.001",
          "max": "2",
          "fee": "0.0004",
          "enabled": true
        }
      }
    ]
  },
  {
    "asset": "ETH",
    "name": "Ethereum",
    "status": "ACTIVE",
    "networks": [
      {
        "name": "ERC20",
        "deposit": {
          "min": "0.01",
          "confirmations": 20,
          "enabled": true
        },
        "withdraw": {
          "min": "0.02",
          "max": "100",
          "fee": "0.0015",
          "enabled": true
        }
      }
    ]
  }
]

Returns deposit and withdrawal settings for supported exchange assets.

Query Parameters

Parameter Type Required Description
asset string No Asset ticker such as BTC. When omitted the route returns fee data for every asset.

Response Fields

Field Type Description
asset string Asset ticker (e.g., BTC).
name string Asset Name (e.g., Bitcoin).
status string Asset Status (e.g., ACTIVE or INACTIVE).
networks array Network specific configuration objects.
networks[].name string Network identifier.
networks[].deposit.min string Minimum deposit amount allowed.
networks[].deposit.confirmations number Number of required blockchain confirmations.
networks[].deposit.enabled boolean Whether deposits are enabled on the network.
networks[].withdraw.min string Minimum withdrawal amount.
networks[].withdraw.max string Maximum withdrawal amount.
networks[].withdraw.fee string Withdrawal fee charged on the network.
networks[].withdraw.enabled boolean Whether withdrawals are enabled on the network.

Authentication

#!/usr/bin/env python3
import time
import hmac
import hashlib
import requests
import json

BASE_URL = "https://api.giottus.com"
API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"


def stringify_value(val):
    """Stringify primitives and objects consistently with Postman script."""
    if val is None:
        return ""
    if isinstance(val, (dict, list)):
        return json.dumps(val, separators=(",", ":"))  # compact JSON
    return str(val)


def canonical(params: dict) -> str:
    """
    Convert dict to canonical string (sorted keys, skip None/signature).
    Example: {'b':2,'a':1} -> 'a=1&b=2'
    """
    if not isinstance(params, dict):
        return ""
    items = []
    for key in sorted(params.keys()):
        if key.lower() == "signature":
            continue
        val = params[key]
        if val is None:
            continue
        items.append(f"{key}={stringify_value(val)}")
    return "&".join(items)


def sign(query: dict, body: dict) -> str:
    """Build Postman-style payload and return hex HMAC-SHA256 signature."""
    payload = (canonical(query) or "") + (canonical(body) or "")
    return hmac.new(API_SECRET.encode(), payload.encode(), hashlib.sha256).hexdigest()


def place_order():
    timestamp = str(int(time.time() * 1000))
    query = {
        "timestamp": timestamp,
        "recvWindow": "5000",
    }

    body = {
        "symbol": "BTC/INR",
        "action": "BUY",
        "type": "LIMIT",
        "price": "2250000",
        "quantity": "0.001",
    }

    # Compute signature same as Postman
    signature = sign(query, body)
    query["signature"] = signature

    url = f"{BASE_URL}/api/v1/spot/order/create"
    headers = {
        "X-GIOTTUS-APIKEY": API_KEY,
        "Content-Type": "application/json",
    }

    # Send JSON body
    resp = requests.post(url, params=query, data=json.dumps(body), headers=headers, timeout=10)

    try:
        print("Status:", resp.status_code)
        print(json.dumps(resp.json(), indent=2))
    except ValueError:
        print("Status:", resp.status_code)
        print(resp.text)


if __name__ == "__main__":
    place_order()

package main

import (
  "bytes"
  "crypto/hmac"
  "crypto/sha256"
  "crypto/tls"
  "encoding/hex"
  "encoding/json"
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "sort"
  "strings"
  "time"
)

// canonical builds sorted key=value pairs joined by '&', skipping "signature"
func canonical(params map[string]interface{}) string {
  keys := make([]string, 0, len(params))
  for k := range params {
    if strings.EqualFold(k, "signature") {
      continue
    }
    keys = append(keys, k)
  }
  sort.Strings(keys)

  var parts []string
  for _, k := range keys {
    v := params[k]
    if v == nil {
      continue
    }
    switch val := v.(type) {
    case string:
      if val == "" {
        continue
      }
      parts = append(parts, fmt.Sprintf("%s=%s", k, val))
    default:
      jsonVal, _ := json.Marshal(val)
      parts = append(parts, fmt.Sprintf("%s=%s", k, string(jsonVal)))
    }
  }
  return strings.Join(parts, "&")
}

func sign(query, body map[string]interface{}, secret string) string {
  payload := canonical(query) + canonical(body)
  mac := hmac.New(sha256.New, []byte(secret))
  mac.Write([]byte(payload))
  return hex.EncodeToString(mac.Sum(nil))
}

func main() {
  const (
    BASE_URL   = "https://api.giottus.com"
    API_KEY    = "YOUR_API_KEY"
    API_SECRET = "YOUR_API_SECRET"
  )

  // --- Query params ---
  query := map[string]interface{}{
    "timestamp":  fmt.Sprintf("%d", time.Now().UnixNano()/1e6), // ms
    "recvWindow": "5000",
  }

  // --- JSON body ---
  body := map[string]interface{}{
    "symbol":   "BTC/INR",
    "action":   "BUY",
    "type":     "LIMIT",
    "price":    "2250000",
    "quantity": "0.001",
  }

  // --- Compute signature ---
  signature := sign(query, body, API_SECRET)
  query["signature"] = signature

  // Build query string
  q := url.Values{}
  for k, v := range query {
    q.Set(k, fmt.Sprintf("%v", v))
  }

  reqURL := fmt.Sprintf("%s/api/v1/spot/order/create?%s", BASE_URL, q.Encode())

  // Encode JSON body
  jsonBody, err := json.Marshal(body)
  if err != nil {
    log.Fatalf("json marshal error: %v", err)
  }

  req, err := http.NewRequest(http.MethodPost, reqURL, bytes.NewBuffer(jsonBody))
  if err != nil {
    log.Fatalf("request build error: %v", err)
  }

  req.Header.Set("X-GIOTTUS-APIKEY", API_KEY)
  req.Header.Set("Content-Type", "application/json")

  // --- HTTP client (with proper SSL verification) ---
  client := &http.Client{
      Transport: &http.Transport{
          TLSClientConfig: &tls.Config{}, // default verification enabled
      },
      Timeout: 10 * time.Second,
  }

  resp, err := client.Do(req)
  if err != nil {
    log.Fatalf("request error: %v", err)
  }
  defer resp.Body.Close()

  bodyResp, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatalf("read response error: %v", err)
  }

  fmt.Println("Status:", resp.Status)
  fmt.Println("Body:", string(bodyResp))
}

import crypto from 'crypto';
import https from 'https';
import fetch from 'node-fetch'; // needed for Node < 18

const BASE_URL = 'https://api.giottus.com'; // or your prod URL
const API_KEY = 'YOUR_API_KEY';
const API_SECRET = 'YOUR_API_SECRET';

// --- Helper: stringify primitive or object ---
function stringifyValue(value) {
  if (value === undefined || value === null) return '';
  if (typeof value === 'object' && !Array.isArray(value)) {
    return JSON.stringify(value);
  }
  return String(value);
}

// --- Helper: canonical string builder (sorted, skip "signature") ---
function canonical(obj = {}) {
  const entries = Object.entries(obj)
    .filter(([k]) => k.toLowerCase() !== 'signature')
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${stringifyValue(v)}`);
  return entries.join('&');
}

// --- Compute signature ---
function sign(query, body) {
  const payload = (canonical(query) || '') + (canonical(body) || '');
  return crypto.createHmac('sha256', API_SECRET).update(payload).digest('hex');
}

async function placeOrder() {
  const timestamp = Date.now().toString();

  const query = {
    timestamp,
    recvWindow: '5000'
  };

  const body = {
    symbol: 'BTC/INR',
    action: 'BUY',
    type: 'LIMIT',
    price: '2250000',
    quantity: '0.001'
  };

  // --- Generate signature ---
  const signature = sign(query, body);
  query.signature = signature;

  // --- Build query string ---
  const fullQuery = new URLSearchParams(query).toString();
  const url = `${BASE_URL}/api/v1/spot/order/create?${fullQuery}`;

  // --- Send JSON body (no "&" between query and body) ---
  const resp = await fetch(url, {
    method: 'POST',
    headers: {
      'X-GIOTTUS-APIKEY': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });

  const data = await resp.json().catch(async () => ({
    text: await resp.text()
  }));

  console.log('Status:', resp.status);
  console.log('Response:', data);
}

placeOrder().catch(err => console.error('Order failed:', err));

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.*;
import com.fasterxml.jackson.databind.ObjectMapper;

public class SimpleGiottusOrder {

    private static final String BASE_URL = "https://api.giottus.com";
    private static final String API_KEY = "YOUR_API_KEY";
    private static final String API_SECRET = "YOUR_API_SECRET";

    public static void main(String[] args) throws Exception {
        // --- Query params ---
        Map<String, Object> query = new LinkedHashMap<>();
        query.put("timestamp", String.valueOf(System.currentTimeMillis()));
        query.put("recvWindow", "5000");

        // --- JSON body ---
        Map<String, Object> body = new LinkedHashMap<>();
        body.put("symbol", "BTC/INR");
        body.put("action", "BUY");
        body.put("type", "LIMIT");
        body.put("price", "2250000");
        body.put("quantity", "0.001");

        // --- Build signing payload ---
        String payload = canonical(query) + canonical(body);

        // --- Sign ---
        String signature = hmacSHA256(payload, API_SECRET);
        query.put("signature", signature);

        // --- Build query string ---
        String queryString = encodeParams(query);

        // --- Build full URL ---
        URI uri = new URI(BASE_URL + "/api/v1/spot/order/create?" + queryString);

        // --- Convert body to JSON ---
        ObjectMapper mapper = new ObjectMapper();
        String jsonBody = mapper.writeValueAsString(body);

        // --- Build secure request ---
        HttpRequest req = HttpRequest.newBuilder(uri)
                .header("X-GIOTTUS-APIKEY", API_KEY)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();

        // --- Default secure HTTP client (SSL verified) ---
        HttpClient client = HttpClient.newHttpClient();

        // --- Send request ---
        HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());

        System.out.println("Status: " + resp.statusCode());
        System.out.println("Response: " + resp.body());
    }

    // Canonical builder: sorted, skip "signature", stringify values
    private static String canonical(Map<String, Object> params) throws Exception {
        List<String> keys = new ArrayList<>(params.keySet());
        Collections.sort(keys);
        List<String> pairs = new ArrayList<>();

        ObjectMapper mapper = new ObjectMapper();
        for (String k : keys) {
            if ("signature".equalsIgnoreCase(k)) continue;
            Object v = params.get(k);
            if (v == null) continue;

            String val;
            if (v instanceof Map || v instanceof List) {
                val = mapper.writeValueAsString(v);
            } else {
                val = v.toString();
            }
            if (!val.isEmpty()) pairs.add(k + "=" + val);
        }
        return String.join("&", pairs);
    }

    // URL-encode key=value pairs
    private static String encodeParams(Map<String, Object> params) {
        StringBuilder sb = new StringBuilder();
        boolean first = true;
        for (Map.Entry<String, Object> e : params.entrySet()) {
            if (!first) sb.append('&');
            first = false;
            sb.append(URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8))
                    .append('=')
                    .append(URLEncoder.encode(String.valueOf(e.getValue()), StandardCharsets.UTF_8));
        }
        return sb.toString();
    }

    // HMAC-SHA256 signature (hex lowercase)
    private static String hmacSHA256(String data, String secret) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        mac.init(keySpec);
        byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        StringBuilder hex = new StringBuilder(hash.length * 2);
        for (byte b : hash) {
            hex.append(String.format("%02x", b));
        }
        return hex.toString();
    }
}

Private API Authentication

All private endpoints on the Giottus API require requests to be HMAC signed. This ensures that only authorized clients can access account-specific data.

Required Parameters & Headers

How to Generate a Signature

  1. Collect every query parameter you will send (excluding signature).
  2. Collect every body payload field that will be transmitted in the body (excluding signature).
  3. For each collection, sort the keys alphabetically and concatenate the resulting key=value pairs without adding separators. If a key has multiple values, repeat the key for each value in sorted order.
  4. Concatenate the canonical query string with the canonical body string (query first, then body) without adding extra separators.
  5. Compute an HMAC SHA-256 hash of the concatenated string using your API Secret and hex-encode the result.
  6. Send this value as the signature query parameter.

Example

The samples above sign a request to POST /api/v1/spot/order/create for a BTC/INR limit buy. Successful responses return an order identifier formatted as (eg., 1-91234567-1), which must be supplied when cancelling the order.

Wallet

Balances

Sample response

[
  {
    "asset": "BTC",
    "free": "0.015",
    "locked": "0.002",
    "lockedFd": "0.001",
    "lockedStaking": "0",
    "lockedOtc": "0"
  },
  {
    "asset": "USDT",
    "free": "152.34",
    "locked": "25.00",
    "lockedFd": "0",
    "lockedStaking": "10",
    "lockedOtc": "0"
  }
]

Returns wallet balances associated with the authenticated account. Locked funds are broken down by source and summed for convenience.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
omitZeroBalances boolean No When true (default), hides assets where all balances are zero.

Response Fields

Field Type Description
asset string Asset ticker.
free string Available balance.
locked string Sum of balances locked for trading, withdrawal, staking, P2P, or OTC operations.
lockedFd string Amount locked in fixed deposit products.
lockedStaking string Amount locked in staking.
lockedOtc string Amount locked in OTC trades.

Crypto deposits

Sample response

[
  {
    "action": "Deposit",
    "asset": "ETH",
    "cryptoAmount": "1.5000",
    "status": "SUCCESS",
    "transactionHash": "0xabc123...",
    "time": 1706480012345,
    "network": "ERC20",
    "fromAddress": null,
    "toAddress": "0x4be3...9c42",
    "fee": "0"
  }
]

Lists crypto deposit transactions filtered by asset, status, or time range.

Can't find older entries? Use GET /api/v1/crypto/deposits/historical.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
asset string No Asset ticker such as BTC.
status string No One of SUCCESS, PENDING, or FAILED.
startTime number No Inclusive start time in milliseconds.
endTime number No Inclusive end time in milliseconds. Must be greater than or equal to startTime.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
action string Always Deposit.
asset string Asset ticker.
cryptoAmount string Amount credited.
status string Normalised status (SUCCESS, PENDING, or FAILED).
transactionHash string Blockchain hash when available.
time number Transaction time in milliseconds.
network string Blockchain network identifier.
fromAddress string Source address if provided by the network.
toAddress string Deposit address.
fee string Fee charged by the platform (if any).

Crypto deposits (historical)

Sample response

[
  {
    "action": "Deposit",
    "asset": "ETH",
    "cryptoAmount": "1.5000",
    "status": "SUCCESS",
    "transactionHash": "0xabc123...",
    "time": 1699954412345,
    "network": "ERC20",
    "fromAddress": null,
    "toAddress": "0x4be3...9c42",
    "fee": "0"
  }
]

Returns archived crypto deposit transactions for the authenticated account. Use this endpoint when you need records beyond the rolling window served by GET /api/v1/crypto/deposits.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
asset string No Asset ticker such as BTC.
status string No One of SUCCESS, PENDING, or FAILED.
startTime number No Inclusive start time in milliseconds.
endTime number No Inclusive end time in milliseconds. Must be greater than or equal to startTime.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
action string Always Deposit.
asset string Asset ticker.
cryptoAmount string Amount credited.
status string Normalised status (SUCCESS, PENDING, or FAILED).
transactionHash string Blockchain hash when available.
time number Transaction time in milliseconds.
network string Blockchain network identifier.
fromAddress string Source address if provided by the network.
toAddress string Deposit address.
fee string Fee charged by the platform (if any).

Crypto withdrawals

Sample response

[
  {
    "action": "Withdrawal",
    "asset": "BTC",
    "cryptoAmount": "0.0200",
    "status": "PENDING",
    "transactionHash": null,
    "time": 1706554410000,
    "network": "BTC",
    "fromAddress": "bc1qxyz...",
    "toAddress": null,
    "fee": "0.0004"
  }
]

Returns crypto withdrawal history for the authenticated account.

Can't find older entries? Use GET /api/v1/crypto/withdrawals/historical.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
asset string No Asset ticker such as BTC.
status string No One of SUCCESS, PENDING, or FAILED.
startTime number No Inclusive start time in milliseconds.
endTime number No Inclusive end time in milliseconds. Must be greater than or equal to startTime.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
action string Always Withdrawal.
asset string Asset ticker.
cryptoAmount string Amount debited.
status string Normalised status (SUCCESS, PENDING, or FAILED).
transactionHash string Blockchain hash when available.
time number Transaction time in milliseconds.
network string Blockchain network identifier.
fromAddress string Source address used by Giottus.
toAddress string Destination address (if known at the time of the request).
fee string Fee charged by the platform.

Crypto withdrawals (historical)

Sample response

[
  {
    "action": "Withdrawal",
    "asset": "BTC",
    "cryptoAmount": "0.0150",
    "status": "SUCCESS",
    "transactionHash": "5d8fabc...",
    "time": 1698800010000,
    "network": "BTC",
    "fromAddress": "bc1qxyz...",
    "toAddress": "bc1qarchive...",
    "fee": "0.0004"
  }
]

Returns archived crypto withdrawal transactions. Use this endpoint when you need records beyond the retention window covered by GET /api/v1/crypto/withdrawals.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
asset string No Asset ticker such as BTC.
status string No One of SUCCESS, PENDING, or FAILED.
startTime number No Inclusive start time in milliseconds.
endTime number No Inclusive end time in milliseconds. Must be greater than or equal to startTime.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
action string Always Withdrawal.
asset string Asset ticker.
cryptoAmount string Amount debited.
status string Normalised status (SUCCESS, PENDING, or FAILED).
transactionHash string Blockchain hash when available.
time number Transaction time in milliseconds.
network string Blockchain network identifier.
fromAddress string Source address used by Giottus.
toAddress string Destination address (if known at the time of the request).
fee string Fee charged by the platform.

Fiat deposits

Sample response

[
  {
    "action": "Deposit",
    "amount": "50000",
    "fee": "0",
    "status": "SUCCESS",
    "referenceId": "RCP987654321",
    "time": 1706400005123
  }
]

Returns INR deposit transactions routed through supported payment gateways.

Can't find older entries? Use GET /api/v1/fiat/deposits/historical.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
status string No One of SUCCESS, PENDING, FAILED, or REJECTED.
startTime number No Inclusive start time in milliseconds.
endTime number No Inclusive end time in milliseconds. Must be greater than or equal to startTime.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
action string Always Deposit.
amount string Amount credited in INR.
fee string Fee charged (if any).
status string Normalised status. One of SUCCESS, PENDING, FAILED, or REJECTED.
referenceId string Payment gateway or internal reference identifier.
time number Transaction time in milliseconds.

Fiat deposits (historical)

Sample response

[
  {
    "action": "Deposit",
    "amount": "75000",
    "fee": "0",
    "status": "SUCCESS",
    "referenceId": "RCP123456789",
    "time": 1697452205123
  }
]

Returns archived INR deposit transactions for the authenticated account. Use this endpoint when the standard GET /api/v1/fiat/deposits route no longer returns the records you need.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
status string No One of SUCCESS, PENDING, FAILED, or REJECTED.
startTime number No Inclusive start time in milliseconds.
endTime number No Inclusive end time in milliseconds. Must be greater than or equal to startTime.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
action string Always Deposit.
amount string Amount credited in INR.
fee string Fee charged (if any).
status string Normalised status. One of SUCCESS, PENDING, FAILED, or REJECTED.
referenceId string Payment gateway or internal reference identifier.
time number Transaction time in milliseconds.

Fiat withdrawals

Sample response

[
  {
    "action": "Withdrawal",
    "amount": "25000",
    "fee": "15",
    "status": "PENDING",
    "referenceId": "WD123456789",
    "time": 1706491122334
  }
]

Returns INR withdrawal transactions initiated from the authenticated account.

Can't find older entries? Use GET /api/v1/fiat/withdrawals/historical.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
status string No One of SUCCESS, PENDING, FAILED, or REJECTED.
startTime number No Inclusive start time in milliseconds.
endTime number No Inclusive end time in milliseconds. Must be greater than or equal to startTime.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
action string Always Withdrawal.
amount string Amount debited in INR.
fee string Fee charged (if any).
status string Normalised status. One of SUCCESS, PENDING, FAILED, or REJECTED.
referenceId string Payment gateway or internal reference identifier.
time number Transaction time in milliseconds.

Fiat withdrawals (historical)

Sample response

[
  {
    "action": "Withdrawal",
    "amount": "40000",
    "fee": "15",
    "status": "SUCCESS",
    "referenceId": "WD987654321",
    "time": 1698127722334
  }
]

Returns archived INR withdrawal transactions. Use this endpoint when the standard GET /api/v1/fiat/withdrawals route no longer includes the records you need.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
status string No One of SUCCESS, PENDING, FAILED, or REJECTED.
startTime number No Inclusive start time in milliseconds.
endTime number No Inclusive end time in milliseconds. Must be greater than or equal to startTime.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
action string Always Withdrawal.
amount string Amount debited in INR.
fee string Fee charged (if any).
status string Normalised status. One of SUCCESS, PENDING, FAILED, or REJECTED.
referenceId string Payment gateway or internal reference identifier.
time number Transaction time in milliseconds.

Spot

Create order

Sample request

POST /api/v1/spot/order/create?timestamp=1706602000123&recvWindow=5000&signature=<calculated> HTTP/1.1
Host: https://api.giottus.com
X-GIOTTUS-APIKEY: YOUR_API_KEY
Content-Type: application/json

{"symbol":"BTC/INR","action":"BUY","type":"LIMIT","price":"2250000","quantity":"0.001"}

Successful response

{
  "data": {
    "order_id": "1-91234567-1"
  }
}

Creates a new spot order. Submit the payload as application/json; numeric fields must be positive decimal strings. At present only LIMIT orders are accepted.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed over the canonical query string concatenated with the canonical form body.

Body Payload (application/json)

Field Type Required Description
symbol string Yes Trading pair in BASE/QUOTE format such as BTC/INR.
action string Yes One of BUY or SELL.
type string Yes Order type. Currently only LIMIT is allowed.
price string Yes Limit price as a positive decimal string.
quantity string Yes Quantity to trade as a positive decimal string.

Responses

Cancel order

Sample request

POST /api/v1/spot/order/cancel?timestamp=1706602005123&signature=<calculated> HTTP/1.1
Host: https://api.giottus.com
X-GIOTTUS-APIKEY: YOUR_API_KEY
Content-Type: application/json

{"order_id":"1-91234567-1"}

Cancels a single order by identifier returned during creation (format 1-123-1). Provide the order_id in an application/json body.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature covering the canonical query string concatenated with the canonical form body.

Body Payload (application/json)

Field Type Required Description
order_id string Yes Identifier returned when the order was created (format 1-123-1).

Responses

Cancel orders by symbol

Cancels every open order for the provided trading pair. Provide the target symbol in an application/json body.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature covering the canonical query string concatenated with the canonical form body.

Body Payload (application/json)

Field Type Required Description
symbol string Yes Trading pair in BASE/QUOTE format such as BTC/USDT.

Responses

Cancel all orders

Cancels every open order for the authenticated account across all symbols. This route does not accept a body.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature covering the canonical query string (no body is sent).

Responses

Open orders

Sample response

[
  {
    "symbol": "ETH/USDT",
    "orderId": "1-91234567-1",
    "price": "1705.00",
    "origQty": "2",
    "executedQty": "0.5",
    "remainingQty": "1.5",
    "status": "PARTIALLY_FILLED",
    "type": "LIMIT",
    "side": "BUY",
    "time": 1706598822000
  }
]

Lists all currently open spot orders (statuses NEW or PARTIALLY_FILLED). When a symbol is provided the results are scoped to that market.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
symbol string No Trading symbol such as ETH/USDT.

Response Fields

Field Type Description
symbol string Trading pair symbol.
orderId string Order identifier in the format 1-123-1.
price string Price submitted for limit or stop-limit orders (0 for market orders).
origQty string Original quantity requested.
executedQty string Quantity that has been filled so far.
remainingQty string Quantity still open.
status string Normalised order status (e.g., NEW, PARTIALLY_FILLED).
type string Order type (MARKET, LIMIT, STOP_MARKET, STOP_LIMIT).
side string Side of the order (BUY or SELL).
time number Order creation time in milliseconds.

Trade history

Sample response

[
  {
    "symbol": "BTC/USDT",
    "id": 601234,
    "orderId": "1-123-1",
    "price": "26800.50",
    "qty": "0.002",
    "quoteQty": "53.601",
    "commission": "0.000002",
    "commissionAsset": "BTC",
    "tds": "0",
    "time": 1706599900456,
    "isBuyer": true,
    "isMaker": false
  }
]

Returns executed spot trades for a specific market. Provide either an order identifier, a time range, or a starting trade identifier—combinations outside the allowed set are rejected.

Can't find older trades? Use GET /api/v1/spot/trades/historical.

Allowed combinations:

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
symbol string Yes Trading pair in BASE/QUOTE format, such as BTC/USDT.
orderId string No Filter by the order id.
startTime number No Earliest execution time in milliseconds.
endTime number No Latest execution time in milliseconds. Must be within 72 hours of startTime and not less than it.
fromId number No Return trades with identifiers greater than or equal to this value.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
symbol string Trading pair in BASE/QUOTE format. such as BTC/USDT.
id number Trade identifier.
orderId string Order identifier associated with the fill.
price string Execution price.
qty string Base asset quantity filled.
quoteQty string Quote asset amount filled.
commission string Fee charged for the trade.
commissionAsset string Asset in which the commission was charged.
tds string Tax Deducted at Source amount if applicable.
time number Execution time in milliseconds.
isBuyer boolean true if you were the buyer in the trade.
isMaker boolean true if your order provided liquidity.

Trade history (historical)

Sample response

[
  {
    "symbol": "BTC/USDT",
    "id": 412345,
    "orderId": "1-123-1",
    "price": "25800.50",
    "qty": "0.002",
    "quoteQty": "51.601",
    "commission": "0.000001",
    "commissionAsset": "BTC",
    "tds": "0",
    "time": 1695000000456,
    "isBuyer": false,
    "isMaker": true
  }
]

Returns archived spot trade records for the authenticated account. Use this endpoint when the standard GET /api/v1/spot/trades route no longer returns older fills.

Allowed combinations:

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
symbol string Yes Trading pair in BASE/QUOTE format, such as BTC/USDT.
orderId string No Filter by the order id.
startTime number No Earliest execution time in milliseconds.
endTime number No Latest execution time in milliseconds. Must be within 72 hours of startTime and not less than it.
fromId number No Return trades with identifiers greater than or equal to this value.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
symbol string Trading pair in BASE/QUOTE format. such as BTC/USDT.
id number Trade identifier.
orderId string Order identifier associated with the fill.
price string Execution price.
qty string Base asset quantity filled.
quoteQty string Quote asset amount filled.
commission string Fee charged for the trade.
commissionAsset string Asset in which the commission was charged.
tds string Tax Deducted at Source amount if applicable.
time number Execution time in milliseconds.
isBuyer boolean true if you were the buyer in the trade.
isMaker boolean true if your order provided liquidity.

SBS

Trades

Sample response

[
  {
    "symbol": "BTC/INR",
    "id": 340012,
    "price": "2250000",
    "qty": "0.001",
    "quoteQty": "2250",
    "commission": "0.90",
    "commissionAsset": "INR",
    "tds": "0.30",
    "time": 1706595555000,
    "isBuyer": true,
    "isMaker": false
  }
]

Returns completed simple buy/sell (SBS) trades for INR markets. Symbols must use the COIN/INR format.

Query Parameters

Parameter Type Required Description
timestamp number Yes Epoch time in milliseconds used for request signing.
recvWindow number No Custom receive window in milliseconds (default 5000, max 60000).
signature string Yes HMAC SHA-256 signature computed from query parameters.
symbol string Yes SBS trading pair such as BTC/INR.
orderId number No Filter by a specific SBS order identifier.
startTime number No Earliest execution time in milliseconds.
endTime number No Latest execution time in milliseconds. Must be within 72 hours of startTime and not less than it.
fromId number No Return trades with identifiers greater than or equal to this value.
limit integer No Maximum records to return (default 20, max 50).

Response Fields

Field Type Description
symbol string SBS trading pair (COIN/INR).
id number SBS order identifier.
price string Executed price in INR.
qty string Coin quantity filled.
quoteQty string INR amount filled.
commission string Fee charged for the trade.
commissionAsset string Asset used to pay the commission (coin or INR depending on side).
tds string Tax Deducted at Source amount if applicable.
time number Execution time in milliseconds.
isBuyer boolean true if you bought the coin.
isMaker boolean Always false because SBS trades do not differentiate maker/taker roles.

FAQ

Do I need an API key for public endpoints?
No. Public endpoints don’t require authentication.

What’s the base URL?
https://api.giottus.com

Is there a sandbox/testnet?
Not yet. All calls hit production.

What is recvWindow and what values are allowed?
It’s the tolerated clock skew in milliseconds. Default is 5000; maximum is 60000.

My private request says INVALID_TIMESTAMP. What should I check?
Verify you’re sending epoch milliseconds, your system clock is NTP-synced, and the request arrives within recvWindow.

How do I generate the HMAC signature?
Build the canonical query string (excluding signature), build the canonical form body whenever you send one (again excluding signature), concatenate them, apply HMAC-SHA256 with your API secret, hex-encode, and send the result as the signature query parameter.

Which header carries my API key?
X-GIOTTUS-APIKEY.

What does the spot order_id look like?
It’s 1-123-1 (e.g., 1-91234567-1). Use the full string for cancellations and when filtering trade history.

Do private endpoints also enforce IP whitelists?
Yes. If configured, calls from non-whitelisted IPs fail with IP_NOT_ALLOWED.

How are rate limits applied?
By IP for public endpoints and by API key for private endpoints. When limited, standard X-RateLimit-* headers are returned and HTTP 429 is used.

What error format should I expect?
JSON like {"code": <number>, "msg": "description"} plus an HTTP status (e.g., 401, 429).

What number format is used in responses?
Numeric fields are returned as strings to preserve precision (e.g., prices, quantities, fees).

Do responses include fields that might be null?
Yes, some fields (e.g., transactionHash) may be null if not applicable yet.

Is pagination supported?
For list endpoints, use the documented limit (default 20, max 50). If a pagination token is introduced in the future, it will be documented per route.

What’s the default limit if I don’t pass one?
20 (max 50) unless otherwise stated.

Can I place spot orders through this API?
Yes. Authenticated clients can create spot orders (BUY/SELL), cancel them individually or per symbol, and fetch open orders/trade history.

How do I rotate or revoke an API key?
Create a new key, update your services to use it, then delete the old key in the API Management page.

How should I retry failed requests?
For transient errors (429, 503, 504), use exponential backoff and respect Retry-After when present. Don’t retry non-transient auth/validation errors until fixed.

Sign Up for a Developer Key

To start using the Giottus API, you need to create a developer key. This key will be used to authenticate private requests and manage your access permissions.

Steps to Get Your Key

  1. Log in to your Giottus account Go to Giottus API Management.

  2. Generate a new API key

  1. Store your credentials securely

⚠️ Important: Your API Secret is shown only once at the time of key creation. Make sure to copy and store it securely. If lost, you will need to generate a new key.

Errors

Giottus API uses numeric error codes in the response body alongside conventional HTTP status codes. All errors are returned as JSON in the form { "code": <number>, "msg": "description" }.

Error Code HTTP Status Meaning
-1125 503 We are currently under maintenance. Please try again after some time.
-1404 404 Endpoint disabled.
-1000 500 Request could not be processed.
-1001 403 Authentication credentials are required for this request.
-1003 429 Too many requests.
-1009 500 Route validation failed.
-1015 403 IP address not allowed.
-1021 400 Timestamp for this request is outside the recvWindow.
-1022 403 Signature for this request is not valid.
-1023 400 recvWindow must be a positive number within the allowed maximum.
-1102 400 Order id is required.
-1103 400 Symbol parameter is required.
-1104 400 Limit must be a numeric value.
-1105 400 Limit is outside the allowed range.
-1106 400 Timestamp parameter is invalid.
-1107 400 Start time must be before end time and within the allowed window.
-1108 400 Status parameter is invalid.
-1109 400 Provided parameters cannot be used together.
-1111 400 Asset format is invalid.
-1112 400 Action parameter is invalid.
-1113 400 Order type parameter is invalid.
-1114 400 Price parameter is invalid.
-1115 400 Quantity parameter is invalid.
-1121 400 Invalid symbol.
-1122 400 Invalid asset.
-1123 400 Symbol format is invalid. Expected format BASE/QUOTE.
-1124 400 Order id format is invalid.
-2003 403 Permission not granted for this action.
-2004 403 Unable to identify account for the provided API key.
-2015 403 Invalid API-key, IP, or permissions for action.
-3000 500 Authentication error.
-4001 500 Internal server error.
-5001 500 Unable to fetch ticker data.
-5002 500 Unable to fetch trades data.
-5003 500 Unable to fetch order book data.
-5004 500 Unable to fetch fees data.
-5005 500 Unable to fetch wallet data.
-5006 500 Unable to fetch crypto deposit data.
-5007 500 Unable to fetch crypto withdrawal data.
-5008 500 Unable to fetch fiat deposit data.
-5009 500 Unable to fetch fiat withdrawal data.
-5010 500 Unable to fetch open orders.
-5011 500 Unable to fetch spot trade history.
-5012 500 Unable to fetch simple buy/sell trade history.
-5013 500 Unable to create spot order.
-5014 500 Unable to cancel spot order
-5015 500 Unable to fetch market symbols.