v4 Documentation [beta]

V4 is the latest upgrade of Stork's Hybrid Oracle as of March 2024. The intended use for this API is for the dApp to consume the data off-chain, and submit to compatible chains, such as StarkEx, Arbitrum, and others, where the data can be verified. Updates include latency <10ms and default update frequency of 500ms or 10bps.

Configuration

• Each asset's price feed will update instantaneously either:

  • if the price has moved by 0.1% (10bp), or

  • if it has been 500 milliseconds since the previous update.

• Currently supported assets

Connection

The websocket server accepts connections at:

• /stark/subscribe

• /evm/subscribe

Authentication

The websocket connection request must include an Authorization header with a valid token value.

For example:

wscat -c '[WEBSOCKET URL]' --auth 'user:password'

wscat -c '[WEBSOCKET URL]' -H "Authorization: Basic $(echo -n 'user:password' | base64)"

Compression

Only compressed websocket streams are supported. Clients can enable compression by including the permessage-deflate extension in the websocket handshake request. The wscat tool does this by default, but here is an explicit example:

wscat -c '[WEBSOCKET URL]' --auth 'user:password' -H 'Sec-Websocket-Extensions: permessage-deflate'

Keep alive

Connections are expected to send websocket ping/pong frames at least every minute else they will be disconnected. These are websocket protocol level ping/pong, most clients/libraries do this automatically for you.

Rate Limits

Rate limits are tied to authentication tokens (see Authentication).

Rate limits are enforced separately for the /stark/subscribe and /evm/subscribe endpoints.

Connection rate limits

Users are allowed 10 live connections total, and up to 10 connection attempts a second. Connection attempts after violating either of these rate limits will be rejected with a 429 HTTP response code until the user is no longer in violation.

Message rate limits

Each websocket connection is allowed to send up to 5 messages a second. Connections that violate this rate limit will be disconnected.

Subscribing

After connecting, users should send a subscription message containing a list of assets to subscribe to.

• For better throughput and resource utilization, we recommended subscribing to all desired assets on a single connection.

Example subscribe message:

{
  "type": "subscribe", 
  "trace_id": "123",   // optional, will be echoed back in the response
  "data": [
    "BTCUSD", 
    "ETHUSD", 
    "BTCUSDMARK"
  ]
}  

A subscription response will contain your connection's current list of subscribed assets.

An example subscription response:

{
  "type": "subscribe",
  "trace_id": "123",
  "data": {
    "subscriptions": [
      // includes all current subscriptions, not just those in the request (e.g. ARBUSDMARK)
      "BTCUSD",
      "ETHUSD",
      "ARBUSDMARK",   
      "BTCUSDMARK"
    ]
  }
}

Unsubscribing

To unsubscribe from receiving price updates for certain assets, send an unsubscription message:

{
  "type": "unsubscribe", 
  "data": [
    "BTCUSD", 
    "ETHUSD"
  ]
}  

An unsubscription response will contain the connections resulting list of subscriptions:

{
  "type": "unsubscribe",
  "data": {
    "subscriptions": [
      "ARBUSDMARK",
      "BTCUSDMARK"
    ]
  }
}

Aggregated price updates

After subscribing to assets (and possibly before receiving the response) users should expect to receive messages with "type": "aggregated_signed_prices" with following formats based on which endpoint (/stark/subscribe vs. /evm/subscribe) you connected to:

Example stark aggregated price update:

{
  "type": "oracle_prices",
  "data": {
    "BTCUSD": {
      "timestamp": 1710793255893000000,
      "asset_id": "BTCUSD",
      "signature_type": "stark",
      "trigger": "clock",
      "price": "67136003187500004000000",
      "signed_prices": [
        {
          "publisher_key": "0x2af6b47b91065e079b4481923bfef55b9bee017824e87a07c6b93826938cc15",
          "external_asset_id": "0x4254435553440000000000000000000064656f787973",
          "signature_type": "stark",
          "price": "67139662309000004000000",
          "timestamped_signature": {
            "signature": {
              "r": "0x21831260ced1f96ad9668feed5952f3d8c12d4a83c091c46028c5c78b11b86d",
              "s": "0x4c93a0d64388c48e02fc5c6a9380e79f0ef59bae595757f91a86b12e2f6d1d3"
            },
            "timestamp": 1710793255662000000,
            "msg_hash": "0x157f10eb4871a08dd447fd19919551375c1a23cc69ae4f77acf9f53d42ca0b9"
          }
        },
        {
          "publisher_key": "0x7884106fe3eb409b15060046ff09c8b12795c1e7b1dd5dce4356c73d460d0d3",
          "external_asset_id": "0x42544355534400000000000000000000616e6f72697468",
          "signature_type": "stark",
          "price": "67130784981000006000000",
          "timestamped_signature": {
            "signature": {
              "r": "0x7ee801acb04d23869406db1eb32028c3a622e92a8514facd6f1a81448eef80e",
              "s": "0x24effc9f672086978cf2bea500bc0b61f700d68b7d2e8623186542bdc6e93e4"
            },
            "timestamp": 1710793255662000000,
            "msg_hash": "0xfe646785414b61892b18da221d27a28c9cd2724aaaaddf8e94dde92e2c04cf"
          }
        },
        // ... more signed prices
      ]
    },
    // ... more assets
  }
}

Example evm aggregated price update:

{
  "type": "oracle_prices",
  "data": {
    "BTCUSD": {
      "timestamp": 1710793460536000000,
      "asset_id": "BTCUSD",
      "signature_type": "evm",
      "trigger": "clock",
      "price": "67102388324000000000000",
      "signed_prices": [
        {
          "publisher_key": "0x99e295e85cb07c16b7bb62a44df532a7f2620237",
          "external_asset_id": "BTCUSD",
          "signature_type": "evm",
          "price": "67103323593999999000000",
          "timestamped_signature": {
            "signature": {
              "r": "0xddf82a82acdd8c8e6013e11bc7ce48dde448ee7dd45afcc7624c48fd353c19fb",
              "s": "0x357394c65988ae3b8a8c842e1b58644cdf2eaa71ba264667428e12bb57d2bf7b",
              "v": "0x1b"
            },
            "timestamp": 1710793460536000000,
            "msg_hash": "0x54b8509f1adb8b14a198b563e19c885ba6b399e36f68b86a587d666460ccca8f"
          }
        },
        {
          "publisher_key": "0xa63f5c960e57f6f0dda4fdb7e452e4dfc5e332dd",
          "external_asset_id": "BTCUSD",
          "signature_type": "evm",
          "price": "67094088774999999000000",
          "timestamped_signature": {
            "signature": {
              "r": "0x71a8073e64a70becd98ee70800fd52b1fd9f5b286ce25a3f86f6931d8c457694",
              "s": "0x773cdc496cf6965e6bbccade7fa816133829db5e141b857e92bf015dfb738c5d",
              "v":"0x1c"
            },
            "timestamp": 1710793460536000000,
            "msg_hash": "0x9ceec9a17c4d8974d435b0129a605878be09db7679a1c6ada99ffa3479371963"
          }
        },
        // ... more signed prices
      ]
    },
    // ... more assets
  }
}