What is GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

Ginses offers a blazing fast low latency GraphQL engine that allows the user to query, aggregate, and stream the market data in real-time.

Requirements

Ginses GraphQL engine supports many front-end and backend clients, available in your favorite programming languages. We recommend well-maintained ones such as the Apollo client library, which support subscriptions (data streaming in real-time over WebSocket)

Definitions

DefinitionDescription
GraphQL URIThe URL which all API request endpoints and URLs are based on.
Access TokenThe access key assigned to your account and used to authenticate with the API.
SymbolThe three-letter currency code or currency pair (e.g., EUR, EURUSD).
Base CurrencyThe currency to which exchange rates are relative to. (If 1 USD = X EUR, USD is the base currency)
Target CurrencyThe currency an amount is converted to. (If 1 USD = X EUR, EUR is the target currency)
Timestamp formatAll timestamps are unix/epoch timestamps (seconds that have passed since since January 1, 1970 UTC).

GraphQL URI

Ginses GraphQL URI’s support http and websocket protocols. The server enables you to query and/or subscribe (stream) one or many asset codes or pairs, with readable parameters. Depending on your subscription plan, the server will return real-time exchange rate data.

HTTP query requests

https://ql.ginses.com/v3

Websocket GraphQL subscriptions

wss://ql.ginses.com/v3

Authentication

Your token is a unique access key passed into the GraphQL request header to authenticate with the Ginses API. Visit “My Account” and locate your token.

Ginses uses an authentication header ginses-token. To authenticate a request, you can pass your ginses-token in the request header.

The following is an example of how to append the access token for authentication:

curl --header "Content-Type: application/json" \
  --header "ginses-token: ACCESS_TOKEN" \
  --request POST \
  --data '{"query": "query Asset {markets(where: {s: {_in: [\"EURUSD\"]}}) {a b t tms}}"}' \
 https://ql.ginses.com/v3

Available symbols (assets)

To get the complete list of a specific market (e.g., Forex, Crypto, etc.) available symbols/assets, use the following example query. Replace the MARKET_NAME with the targeted market (e.g. crypto, fx, etc.)

curl --header "Content-Type: application/json" \
  --header "ginses-token: ACCESS_TOKEN" \
  --request POST \
  --data '{"query": "query available_assets {markets(where: {m: {_eq: \"fx\"}}) {s n}}"}' \
 https://ql.ginses.com/v3
// query example
query available_assets {
  markets(where: {m: {_eq: "fx"}}) {
    n
    s
  }
}

Market’s data query

Ginses provides the ability to query any available symbols/asset, base currency (e.g., EUR) or exact currency pair (e.g.,EURUSD).

Search symbols

// example query
query search_query {
  markets(where: {s: {_regex: "USD"}}) {
    s
    a
    b
    t
  }
}

Reponse

// response example
{
  "data": {
    "markets": [
      {
        "s": "ZRXUSD",
        "a": 0.301323,
        "b": 0.300404,
        "t": "2022-07-17T21:07:40.482"
      },
      {
        "s": "ZMWUSD",
        "a": 0.06101,
        "b": 0.06021,
        "t": "2022-07-17T20:57:21.257"
      }
    ]
  }
}

Query Symbol

// example query
query get_symbol {
  markets(where: {s: {_eq: "EURUSD"}}) {
    s
    a
    b
    t
  }
}

Reponse

// response example
{
  "data": {
    "markets": [
      {
        "s": "EURUSD",
        "a": 1.00847,
        "b": 1.00839,
        "t": "2022-07-17T21:11:01.116"
      }
    ]
  }
}

GraphQL Subscriptions

Subscriptions are a GraphQL feature that allows a server to send data to its clients when a specific event happens. Subscriptions are usually implemented with WebSockets. In that setup, the server maintains a steady connection to its subscribed client.

Ginses GraphQL Subscriptions enables the systems to stream real-time market data updates from the GraphQL server to the subscribed clients.

Getting Started with subscriptions

In your application’s client, you can replace your query with a the subscription you want your app to execute, like so:

// example subscription
subscription stream_symbol {
  markets(where: {s: {_eq: "EURUSD"}}) {
    s
    a
    b
    t
  }
}

Fields glossary

KeyDescription
tThe last update date/time of query result.
tmsThe last update timestamp of query result.
sAsset’s symbol or currency pair (e.g., EURUSD, AAPL, BTCUSD)
bThe bid price. It is also referring to the highest price a buyer will pay for a currency.
bdThe bid price direction. It is also referring to the color code of the displayed bid price (e.g., red/green).
aThe ask price. It is also referring to the lowest price a seller will accept for a currency.
adThe ask price direction. It is also referring to the color code of the displayed ask price (e.g., red/green).
pThe symbol’s price precision
vVolume
cDaily change
cpDaily change percentage
hDaily high
lDaily Low
mMarket (e.g., FX, Crypto, Future, etc.)
nFull symbol name (e.g., EURO / U.S. DOLLAR)
ucUSD conversion
mgMargin calculation (trading aggregation support)
mgbMargin calculation base pair position (trading aggregation support). e.g., BASE/USD => “0”

Example query with all fields

query MyQuery {
  markets(where: {s: {_eq: "EURUSD"}}) {
    s
    a
    b
    t
    v
    uc
    ts
    tms
    p
    n
    mgb
    mg
    m
    lp
    l
    h
    cp
    c
    bd
    ad
  }
}