Websocket


💡 Production Url: wss://ws.trever.io

Introduction

When connected you will receive a welcome message:

{
  "type": "welcome",
  "data": {
    "websocket_type": "<TYPE>"
  }
}

Headers

When connecting to a websocket endpoint please use the following headers:

  • Host: ws.trever.io
  • Connection: Upgrade
  • Upgrade: websocket
  • Sec-WebSocket-Key: <calculated at runtime>
  • Sec-WebSocket-Version: 13
  • Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits

All messages are sent as a text message containing json objects.

Errors

On errors in REST- and Websocket API you will receive a error message:

{
  "type": "error",
  "data": {
    "code": 1002,
    "message": "error getting jwt token: illegal base64 data at input byte 340"
  }
}
Name Type Description
code integer Error code.
message string Error message.

Error Codes

Code Description
1000 Unknown error.
1001 Internal error.
1002 Authorization required.
1003 Bad request.
2000 Subscription error.
2001 Invalid request.

Executions

Path: /execution

Subscribes to the current execution stream of our workspace. The stream will receive any execution updates in realtime and is able to execute new ones

Stream Eventes (Response)

These events will continuously return from the stream if execution events happen.

{
  "type": "execution",
  "data": {
    "id": "64b955f8-5e97-460a-bcca-11b530462391",
    "workspace": "trever",
    "amount": "1",
    "price": null,
    "margin": "0.1",
    "risk": "0.001002",
    "route": {
      "id": "517652e2-8d27-437a-822d-2bf586846181",
      "name": "ADA/EUR SB",
      "workspace": "trever",
      "base_asset": "ADA",
      "quote_asset": "EUR",
      "hops": [
        {
          "hop_no": 0,
          "venue_id": "52b140db-30a6-4803-89a0-bb263294e66e",
          "base_asset": "ADA",
          "quote_asset": "EUR"
        }
      ],
      "margin": null,
      "risk_quantile": null
    },
    "execution_type": "MARKET",
    "slippage": "0",
    "side": "BUY",
    "client_ref": "1234",
    "internal_ref": "",
    "state": "DONE",
    "reason": null,
    "retry_count": 0,
    "hop_infos": [
      {
        "execution_id": "64b955f8-5e97-460a-bcca-11b530462391",
        "hop_no": 0,
        "retry_count": 0,
        "id": "d3ff588a-874c-42d1-a637-a2b7605e76fc",
        "state": "DONE",
        "reason": null,
        "order_id": "334a94bb-5a9a-4903-b9eb-b7119789e2d3",
        "fills": [
          {
            "id": "fb88e2a6-8265-48b2-928a-c36a34326d5e",
            "trade_id": "52a38650-f99a-4d7d-a594-fa6d7c067138",
            "order_id": "334a94bb-5a9a-4903-b9eb-b7119789e2d3",
            "foreign_trade_id": "22c43810-1a61-46c7-a75a-f91a3fb537d8",
            "price": "0.448452",
            "amount": "1",
            "fee": "0",
            "volume": "0.45",
            "traded_at": 1707295196792233200,
            "amount_net": "1",
            "price_net": "0.45",
            "volume_net": "0.45"
          }
        ],
        "system_created_at": 0,
        "system_created_by": "",
        "system_updated_at": 0,
        "system_updated_by": ""
      }
    ],
    "closes_position_id": null,
    "fee_aware": false,
    "execution_result": {
      "amount": "1",
      "price": "0.448452",
      "volume": "0.45",
      "amount_net": "1",
      "price_net": "0.45",
      "volume_net": "0.45",
      "price_with_margin_and_risk": "0.4937914837944",
      "volume_with_margin_and_risk": "0.49549599",
      "price_based_on_config": "0.4932972",
      "volume_based_on_config": "0.495"
    },
    "customers": null,
    "customer_execution_results": null,
    "system_created_at": 1707295195753558000,
    "system_created_by": "dev@trever.io",
    "system_updated_at": 1707295197810786300,
    "system_updated_by": "dev@trever.io"
  }
}

Execute

Execution an execution request.

Request

{
  "type": "execute",
  "data": {
    "route_id": "517652e2-8d27-437a-822d-2bf586846181",
    "amount": 1,
    "side": "BUY",
    "execution_type": "MARKET",
    "workspace": "trever"
  }
}
Name Type Mandatory Description
route_id string YES Id of the price stream route.
amount decimal YES Trade amount.
side enum YES Sides: BUY or SELL.
execution_type enum YES Execution Types: MARKET, LIMIT, STOP_MARKET or OWNBOOK
workspace string NO The Workspace.
client_ref string NO Reference will be send on every update of the execution.
id string NO
price decimal NO Trigger price for LIMIT and STOP_MARKET executions.
quote_id string NO
slippage decimal NO Maximum slippage of the price, execution will cancel if slippage is reached.
closes_position_id string NO
customers array NO List of customers with quantities.
customers.customer_id decimal NO Id of the customer.
customers.quantity_absolute decimal NO Asset quantity for the customer.
fee_aware boolean NO
margin decimal NO Margin to add on prices (0.01 = 1%).
risk decimal NO Risk to add on prices (0.01 = 1%).
tif_mode decimal NO Time in Force: GTC, GTD, IOC or FOK
good_till_date timestamp NO Timestamp when the execution gets cancelled on GTD tif_mode.
stop_order_condition string NO Stop Order Condition: TAKE_PROFIT or STOP_LOSS

Response

{
  "type": "execute_received",
  "data": {
    "ok": true
  }
}

Pricestream

Path: /price-stream/prices/stream

Subscribe

Request

{
  "type": "subscribe_price",
  "data": {
    "route_id": "517652e2-8d27-437a-822d-2bf586846181",
    "schedule_ms": 2500,
    "requests": [
      {
        "request_asset": "ADA",
        "request_quantity": "10"
      }
    ]
  }
}
Name Type Mandatory Description
route_id string YES Id of the price stream route.
schedule_ms integer YES Interval for receiving updates (1000 = 1 second).
requests array YES List of assets with quantities.
execution_type enum NO Execution Types: MARKET, LIMIT, STOP_MARKET or OWNBOOK
request_side enum NO Sides: BUY or SELL.
quote_validity_s integer NO Validity duration of quotes (10 = 10 seconds).
customers array NO List of customers with quantities.
customers.customer_id string NO Id of the customer.
customers.quantity_absolute decimal NO Asset quantity for the customer.
margin decimal NO Margin to add on prices (0.01 = 1%).
risk_quantile decimal NO Quantile for risk calculation (0.95 = 95%).
risk_duration_ms integer NO Duration for risk calulation (1000 = 1 second)
client_ref string NO Reference will be send on every price update.

Response

{
  "type": "price_subscribed",
  "data": {
    "topic": {
      "id": "e00637f8-a3ff-4ba1-bb2e-bd6a6251bb27",
      "stream_type": "PRICES",
      "workspace": "trever",
      "quote_validity_s": 180,
      "base_asset": "ADA",
      "quote_asset": "EUR",
      "customers": null,
      "route_id": "517652e2-8d27-437a-822d-2bf586846181",
      "post": {
        "margin": "0",
        "risk_duration_ms": 0,
        "risk_quantile": "0"
      },
      "computation": [
        {
          "venue_id": "52b140db-30a6-4803-89a0-bb263294e66e",
          "venue_code": "TRA_SB",
          "secret_name": "trever/TRA_SB/DEFAULT/0",
          "base_asset": "ADA",
          "quote_asset": "EUR",
          "trading_fees": null
        }
      ],
      "request_side": null,
      "execution_type": null,
      "schedule_ms": 2000,
      "requests": [
        {
          "request_asset": "ADA",
          "request_quantity": "1"
        }
      ],
      "client_ref": "4d92843a-e6b2-49a5-b730-4d7bbe9cb4f7",
      "is_batch": false
    },
    "route_id": "517652e2-8d27-437a-822d-2bf586846181",
    "client_ref": "4d92843a-e6b2-49a5-b730-4d7bbe9cb4f7"
  }
}
Name Type Description
route_id string Id of the price stream route.
client_ref string Reference which was sent on subscribe request.
topic.id string Generated topic id will be sent on price updates and is needed for unsubscription.
topic.stream_type enum
topic.quote_validity_s string Validity duration of quotes (10 = 10 seconds).
topic.base_asset string Base asset.
topic.quote_asset string Quote asset.
topic.customers array List of customers with quantities.
topic.customers.customer_id string Id of the customer.
topic.customers.quantity_absolute decimal Asset quantity for the customer.
topic.route_id string Id of the price stream route.
topic.post.margin decimal Margin sent at subscribe request (0.01 = 1%).
topic.post.risk_duration_ms decimal Duration sent at subscribe request (1000 = 1 second).
topic.post.risk_quantile decimal Quantile sent at subscribe request (0.95 = 95%).
topic.computation list Shows hop information of the route.
topic.request_side enum Side sent at subscribe request.
topic.execution_type enum Type sent at subscribe request.
topic.schedule_ms string Interval sent at subscribe request (1000 = 1 second).
topic.requests array Requests sent at subscribe request.
topic.client_ref array Reference which was sent on subscribe request.
topic.is_batch bool True when multiple customers are set.

Unsubscribe

Request

{
  "type": "unsubscribe_price",
  "data": {
    "topic_id": "e00637f8-a3ff-4ba1-bb2e-bd6a6251bb27"
  }
}
Name Type Mandatory Description
topic_id string YES Id of the topic received at subscribe response.

Response

{
  "type": "unsubscribed",
  "data": {
    "topic_id": "e00637f8-a3ff-4ba1-bb2e-bd6a6251bb27"
  }
}
Name Type Description
topic_id string Id of the topic sent at unsubscribe request.

Prices Updates

{
  "data": {
    "amount_asset": "ADA",
    "base_asset": "ADA",
    "client_ref": "4d92843a-e6b2-49a5-b730-4d7bbe9cb4f7",
    "expire_at": 0,
    "fee_aware": false,
    "id": "0a7eaadd-74ea-46b6-9129-5212b7333504",
    "is_batch": false,
    "margin": "0",
    "price_asset": "EUR",
    "quote_asset": "EUR",
    "responses": [
      {
        "amount_ask": "1",
        "amount_bid": "1",
        "price_ask": "0.473416",
        "price_ask_without_margin_and_risk": "0.473416",
        "price_bid": "0.472635",
        "price_bid_without_margin_and_risk": "0.472635",
        "request_asset": "ADA",
        "request_quantity": "1",
        "risk_fac_ask": "0",
        "risk_fac_bid": "0",
        "volume_ask": "0.473416",
        "volume_ask_without_margin_and_risk": "0.473416",
        "volume_bid": "0.472635",
        "volume_bid_without_margin_and_risk": "0.472635"
      }
    ],
    "risk": {
      "duration_ms": 0,
      "quantile": "0"
    },
    "route_id": "517652e2-8d27-437a-822d-2bf586846181",
    "topic_id": "e00637f8-a3ff-4ba1-bb2e-bd6a6251bb27",
    "volume_asset": "EUR"
  },
  "type": "price"
}
Name Type Description
id string Id of the record.
route_id string Id of the price stream route.
topic_id string Topic received in the subscribe response.
client_ref string Reference sent in subscribe request.
base_asset string Base asset.
quote_asset string Quote asset.
amount_asset string Asset for amount fields.
price_asset string Asset for price fields.
volume_asset string Asset for volume fields.
expire_at int Expiration UTC timestamp (0 = Never).
fee_aware bool
is_batch bool True when multiple customers are set.
margin string Margin sent at subscribe request (0.01 = 1%).
responses array Order book responses of requests sent in the subscribe request.
risk map Risk settings sent in the subscribe request.

Ping

You can send a ping to receive a pong.

Request

{
  "type": "ping"
}

Response

{
  "type": "pong",
  "data": {}
}

Authentication

Before making any authenticated calls to the Websocket API, you need to login through our auth REST endpoint. The returned access_token must be passed as an auth message to an established websocket connection.

Request

{
  "type": "auth",
  "data": {
    "workspace": "<YOUR_WORKSPACE>",
    "token": "<YOUR_TOKEN>"
  }
}
Name Type Mandatory Description
workspace string yes The workspace you want to authenticated on.
token string yes The authentication token.

Response

{
  "type": "auth_result",
  "data": {
    "success": true,
    "workspace": "trever"
  }
}
Name Type Description
success boolean Success state.
workspace string The workspace authenticated on.