GraphQL Quick Start Guide 

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

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

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
  }
}