API reference

List your orders

GET

/v2/orders

const url = 'https://api.hyperstream.dev/v2/orders?state=delivered&limit=20';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.hyperstream.dev/v2/orders?state=delivered&limit=20' \
  --header 'X-API-Key: <X-API-Key>'

Your orders, newest first by build time, always scoped to your key. traces.chainObservations is empty here; read the single order for its trail.

The cursor is a keyset: orders built after your first page do not appear on later pages. Poll the first page for new orders, and keep the filters unchanged while paging.

Authorizations

ApiKeyAuth

Parameters

Query Parameters

depositor

string

/^0x[0-9a-fA-F]{40}$/

Only orders from this depositor.

from

string

Only orders with this source token. Either TRON form matches.

string

Only orders with this destination token. Either TRON form matches.

state

string

Allowed values: pending_deposit deposited published partially_filled terminal_chain withdrawn_on_hub delivered delivery_failed

Only orders in this state.

Example

delivered

cursor

string

/^\d+_0x[0-9a-fA-F]{64}$/

nextCursor from the previous page. Keep the other filters unchanged while paging.

limit

string

/^\d+$/

Page size, clamped to 1–200. Default 50.

Example

Responses

200

A page of orders.

application/json

A page of your orders.

object

orders

required

Newest first by build time.

Array<object>

One order and its lifecycle. Nested objects are null until their event is observed.

object

orderId

required

keccak256(abi.encode(depositor, nonce)), lowercase. Keys every later call: persist it.

string

/^0x[0-9a-fA-F]{64}$/

integrator

required

Your integrator name.

string

srcToken

required

Address in the chain’s native display form: EVM 0x hex, TRON base58.

string

dstToken

required

Address in the chain’s native display form: EVM 0x hex, TRON base58.

string

srcChainId

required

Any of:

integer
null

Spoke chain id.

integer

dstChainId

required

Any of:

integer
null

Spoke chain id.

integer

srcAmountSpoke

required

The deposit, in source base units.

string

/^\d+$/

depositor

required

Lowercase. Compare addresses case-insensitively across endpoints.

string

/^0x[0-9a-fA-F]{40}$/

depositAddress

required

Any of:

string
null

Address in the chain’s native display form: EVM 0x hex, TRON base58.

string

payoutAddr

required

Address in the chain’s native display form: EVM 0x hex, TRON base58.

string

refundAddr

required

Address in the chain’s native display form: EVM 0x hex, TRON base58.

string

fullFee

required

Any of:

string
null

string

/^\d+$/

intentOutcomeRate

required

Any of:

string
null

string

/^\d+$/

state

required

Closed set. Poll until delivered or delivery_failed; withdrawn_on_hub means hub settlement with delivery not yet fully recorded. Use a local timeout and resume by orderId if the result remains unconfirmed.

string

Allowed values: pending_deposit deposited published partially_filled terminal_chain withdrawn_on_hub delivered delivery_failed

deposit

required

Any of:

object
null

object

required

Transaction hash (EVM) or transaction id (TRON).

string

required

When it was observed, unix seconds.

integer

deliver

required

Any of:

object
null

object

payout

required

Any of:

object
null

object

required

string

amount

required

Any of:

string
null

string

/^\d+$/

refund

required

Any of:

object
null

object

required

string

amount

required

Any of:

string
null

string

/^\d+$/

required

When the last recorded leg landed.

integer

deliveryFailed

required

Any of:

object
null

object

msg

required

string

Allowed values: payout failed refund failed payout and refund both failed

payout

required

Any of:

string
null

string

refund

required

Any of:

string
null

string

traces

required

Diagnostics. Track state, deposit and deliver instead.

object

rootIntentId

required

Any of:

string
null

string

/^0x[0-9a-fA-F]{64}$/

publish

required

Any of:

object
null

object

required

Transaction hash (EVM) or transaction id (TRON).

string

required

When it was observed, unix seconds.

integer

withdraw

required

Any of:

object
null

object

required

string

settledOutcome

required

Any of:

string
null

string

/^\d+$/

refundSource

required

Any of:

string
null

string

/^\d+$/

accruedFee

required

Any of:

string
null

string

/^\d+$/

required

integer

chainObservations

required

Ordered trail of the intent and its fills. Always empty in the order list.

Array<object>

object

seq

required

integer

intentId

required

string

/^0x[0-9a-fA-F]{64}$/

intentState

required

string

Allowed values: Open Solved Cancelled

observedTx

required

string

required

integer

nextCursor

required

Any of:

string
null

string

Example

{
  "orders": [
    {
      "orderId": "0x35dc8d390877c71baacadb4001eea0055804cfc306f599fbfc97c1d69d64d30a",
      "integrator": "acme",
      "srcToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "dstToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "srcChainId": 42161,
      "dstChainId": 8453,
      "srcAmountSpoke": "100000000",
      "depositor": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4",
      "depositAddress": null,
      "payoutAddr": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4",
      "refundAddr": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4",
      "fullFee": "349850",
      "intentOutcomeRate": "999700000000000000",
      "state": "delivered",
      "deposit": {
        "tx": "0xa37fc5f866fdd03a6443129b95f5a328eba3a36b0c4d68c467849e846775a04d",
        "at": 1786999720
      },
      "deliver": {
        "payout": {
          "tx": "0x938eedc52713a24442d412eca2d8aae68c3df30fca154226113c438f82df5aa7",
          "amount": "99620254"
        },
        "refund": null,
        "at": 1786999810
      },
      "deliveryFailed": null,
      "traces": {
        "rootIntentId": "0x01cb37f4c5f512f757df0452b51e3fe8daefda8dfdd7e6d298d841ac54f7d18b",
        "publish": {
          "tx": "0xad257bdb68adfa6f6d2bf551f29edeeadc2c58bbbc1806ee42a741c2e36f1d07",
          "at": 1786999745
        },
        "withdraw": {
          "tx": "0x17c2da9cc8b27b31e95406d399f5468b2caddbd272afd102d148a9de5bb5dde5",
          "settledOutcome": "99620254",
          "refundSource": "0",
          "accruedFee": "329910",
          "at": 1786999790
        },
        "chainObservations": []
      }
    }
  ],
  "nextCursor": "1786999700_0x35dc8d390877c71baacadb4001eea0055804cfc306f599fbfc97c1d69d64d30a"
}

400

Invalid query.

application/json

The request failed schema validation. Carries message, not error.

object

message

required

string

Allowed value: Validation failed

name

required

string

Allowed value: ValidationException

details

required

Array<object>

object

field

required

string

message

required

string

code

required

string

Example

{
  "message": "Validation failed",
  "name": "ValidationException"
}

401

The X-API-Key header is missing.

application/json

An error raised by the route itself.

object

error

required

string

detail

object

minSrcAmount

Smallest deposit that would quote, in source base units.

string

/^\d+$/

maxSrcAmount

Largest deposit that would quote, in source base units.

string

/^\d+$/

maxOutcomeAmount

Largest output that would quote, in destination base units.

string

/^\d+$/

missing

The deployment setting this direction needs.

string

Example

{
  "error": "X-API-Key required"
}

403

The key is unknown or past its rotation window. A 403 is always about your account: do not retry.

application/json

An error raised by the route itself.

object

error

required

string

detail

object

minSrcAmount

Smallest deposit that would quote, in source base units.

string

/^\d+$/

maxSrcAmount

Largest deposit that would quote, in source base units.

string

/^\d+$/

maxOutcomeAmount

Largest output that would quote, in destination base units.

string

/^\d+$/

missing

The deployment setting this direction needs.

string

Example

{
  "error": "Unknown or inactive integrator"
}

500

Unhandled failure. Retry once, then escalate with the x-request-id response header.

application/json

Maintenance, a malformed JSON body, or an unhandled failure. Carries message, not error.

object

message

required

string

name

required

MaintenanceException (503), BadRequestException (malformed JSON) or InternalErrorException (500).

string

Example

{
  "message": "Internal Error",
  "name": "InternalErrorException"
}