API reference

Get an order

GET

/v2/orders/{orderId}

const url = 'https://api.hyperstream.dev/v2/orders/0x35dc8d390877c71baacadb4001eea0055804cfc306f599fbfc97c1d69d64d30a';
const options = {method: 'GET'};

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/0x35dc8d390877c71baacadb4001eea0055804cfc306f599fbfc97c1d69d64d30a

One order with its full on-chain trail. Public: the orderId is the only credential, so keep it out of shared URLs, logs and analytics.

Poll every 10 to 15 seconds until state is delivered or delivery_failed. Keep polling through withdrawn_on_hub, which means hub settlement with delivery not yet fully recorded. Use a local timeout and retain the orderId to resume; a timeout means unconfirmed, not failed.

Parameters

Path Parameters

orderId

required

string

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

The orderId from /v2/build. Case-insensitive.

Example

0x35dc8d390877c71baacadb4001eea0055804cfc306f599fbfc97c1d69d64d30a

Responses

200

The order.

application/json

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

Example

{
  "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": [
      {
        "seq": 0,
        "intentId": "0x01cb37f4c5f512f757df0452b51e3fe8daefda8dfdd7e6d298d841ac54f7d18b",
        "intentState": "Solved",
        "observedTx": "0x7de125b4300430bd1801e4d12a10f7e76b9400d2a13eddd207232f63cc546656",
        "at": 1786999770
      }
    ]
  }
}

400

orderId is not 0x plus 64 hex.

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

404

No order with that orderId.

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": "Order not found"
}

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