Connecting

Connect to wss://api.intea.rs/ws. Every message, both ways, is one JSON text message. Messages are compressed with permessage-deflate when the client offers it, as browsers do.

Requests and replies

The client sends requests:

{ "id": 1, "method": "tokens.get", "params": { "fields": ["symbol"], "ids": ["wrap.near"] } }

• id is a number or a string you pick. The reply has the same id.
• params can be left out when a method takes none.
• Replies can come in any order, and at most 16 requests can wait for their reply at once.

The server replies with a result or an error:

{ "id": 1, "result": { ... }, "credits_used": 1 }
{ "id": 1, "error": { "code": "unknown_field", "message": "..." }, "credits_used": 0 }

See Messages for every message the server sends, and Errors for the error codes.

Caution

A message that isn’t a JSON object with an id and a method, or a binary message, closes the connection with code 1008. A message over 64 KiB closes it with 1009.

The first message

The server’s first message is hello, sent once, with the latest block and the limits:

{ "hello": { "version": 2, "height": 219969289, "timestamp_millis": 1792003517185, "limits": { ... } }, "credits_used": 0 }

Right after the server restarts, hello only comes once every token is loaded, so wait for it before counting on replies.

Subscriptions

Methods ending in .subscribe make a subscription. It’s named by the id of the request that made it, and every update it sends, called a push, has that id as sub:

{ "sub": 1, "height": 219969292, "timestamp_millis": 1792003519000, "set": { ... }, "credits_used": 1 }

• The reply comes before the first push, with nothing missed or repeated between them.

• Pushes come in block order across all of a connection’s subscriptions, at most one per subscription per block, and none for a block that changed nothing the subscription follows.

• Changes made outside blocks, like token metadata being refreshed, come with the next block. If no block comes within a second, they come in a push of their own, with the height of the block before them.

• An id can’t be reused while its subscription is active. End it with unsubscribe, which replies {}:

  { "id": 7, "method": "unsubscribe", "params": { "sub": 1 } }

• A connection can have up to 100 subscriptions.

If a request fails, the subscription it would have made doesn’t exist.

Heights

Every reply and push has height and timestamp_millis: the latest block it accounts for. The replies to unsubscribe and schema are the exception. Use height to pick up after a reconnect, see below.

Idle connections

After 15 seconds with nothing else sent, the server sends:

{ "idle": { "height": 219969300, "timestamp_millis": 1792003525000 }, "credits_used": 0 }

so you can tell a quiet connection from a dead one. If nothing at all arrives for much longer than 15 seconds, reconnect.

Slow clients

A client that can’t read pushes as fast as they come isn’t disconnected. Each of its subscriptions catches up in one push instead:

• Token subscriptions send everything that changed since the last push.
• Event subscriptions (trades, transfers, activity) send every event after the last one sent.

Some subscriptions can’t catch up and end with too_far_behind instead:

• An event subscription that falls more than 10,000 rows behind.
• Any balances.subscribe, since balance changes can’t be read back.

When the server ends a subscription, it sends:

{ "sub": 1, "end": { "code": "too_far_behind", "message": "..." }, "credits_used": 0 }

Make the subscription again to carry on.

Tables

Tokens, trades, transfers, balances and holders come as a table, so each field name is sent once instead of in every row:

{
  "columns": ["account_id", "symbol", "price_usd"],
  "rows": [
    ["wrap.near", "wNEAR", "4.81"],
    ["usdt.tether-token.near", "USDt", "1"]
  ]
}

The first column is the row’s key (account_id for tokens, id for trades), then the fields you asked for, in the order you asked for them.

After a reconnect

Connections drop. Each kind of subscription has a way to carry on from where it left off without downloading everything again:

Subscription	How to resume
tokens.subscribe	Same params, with resume_from set to the height of the last reply or push. See Live token lists
trades.subscribe, transfers.subscribe	after_id set to the newest id you have. See History, then live
activity.subscribe	after set to the last of the last reply or push
candles.subscribe, holders.subscribe, balances.subscribe	Subscribe again: the reply has the current state