Skip to content
KhalaniDocs
API reference

Quote a trade

GET
/v2/quote
curl --request GET \
  --url 'https://api.hyperstream.dev/v2/quote?fromChainId=42161&from=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&toChainId=8453&to=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&mode=exact_input&srcAmount=100000000' \
  --header 'X-API-Key: <X-API-Key>'

Prices one direction and size without creating an order. Nothing is stored: build carries a signed attestation, valid for five minutes, that pins /v2/build to these numbers.

mode Send Get back
exact_input (default) srcAmount receive.amount, what the depositor gets
exact_output outcomeAmount spend.amount, the smallest deposit that reaches it

Send exactly the amount mode names: both, neither, or the other one is a 400.

A 200 means the size is fillable now. In exact_input, too small is a 400 carrying detail.minSrcAmount. In exact_output, inspect spend.amount: the required deposit includes fees even for a small requested outcome. Too large is a 409 carrying maxSrcAmount (exact_input) or maxOutcomeAmount (exact_output). Re-quote at the returned figure.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
fromChainId
required
integer

Source spoke chain id.

Example 

42161
from
required
string

Source spoke-token address. TRON accepts base58 or hex41.

Example 

0xaf88d065e77c8cC2239327C5EDb3A432268e5831
toChainId
required
integer

Destination spoke chain id.

Example 

8453
to
required
string

Destination spoke-token address. TRON accepts base58 or hex41.

Example 

0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
mode
string
default: exact_input
Allowed values: exact_input exact_output

Which side you fix: exact_input sends srcAmount, exact_output sends outcomeAmount.

Example 

exact_input
srcAmount
string
/^[1-9]\d*$/

What the depositor spends, in source base units. Required when mode is exact_input; rejected otherwise.

Example 

100000000
outcomeAmount
string
/^[1-9]\d*$/

What the depositor should receive, in destination base units. Required when mode is exact_output; rejected otherwise.

Responses

Section titled “Responses”

200

Section titled “200”

Fillable now. Show spend and receive; send build to /v2/build.

Media typeapplication/json

A price for one direction and size. A 200 means the amount is fillable now. Nothing is stored.

object
spend
required

What the depositor sends, in source base units. Includes every fee.

object
chainId
required

Spoke chain id.

integer
token
required

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

string
symbol
required
string
decimals
required
integer
amount
required
string
/^\d+$/
receive
required

What the depositor receives if the order fills completely, in destination base units. Truncated, never rounded up.

object
chainId
required

Spoke chain id.

integer
token
required

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

string
symbol
required
string
decimals
required
integer
amount
required
string
/^\d+$/
details
required
object
intentOutcomeRate
required

The solver’s rate, 1e18-scaled: destination per source unit of the published amount (after fees), not of the deposit. Not a token amount.

string
/^\d+$/
protocolFee
required

The flat fee plus Khalani’s bps, in source base units. Your commission is not included.

string
/^\d+$/
build
required

The /v2/build request, already assembled. Send it back with depositor (and recipients where required) added.

object
srcToken
required
object
chainId
required

Spoke chain id.

integer
token
required

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

string
dstToken
required
object
chainId
required

Spoke chain id.

integer
token
required

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

string
amount
required

The deposit, in source base units.

string
/^\d+$/
intentOutcomeRate
required

The rate the order will publish at, 1e18-scaled.

string
/^\d+$/
terms
required

Attestation that pins /v2/build to this quote. Always send it back.

object
flatFee
required

Flat fee in 18-decimal hub units. Signed over, so echo it unchanged.

string
/^\d+$/
expiresAt
required

Unix seconds. The attestation is valid for five minutes.

string
/^\d+$/
signature
required

Khalani’s EIP-712 attestation over the quoted trade.

string
/^0x[0-9a-fA-F]*$/

Example 

{
  "spend": {
    "chainId": 42161,
    "token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "symbol": "USDC",
    "decimals": 6,
    "amount": "100000000"
  },
  "receive": {
    "chainId": 8453,
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "symbol": "USDC",
    "decimals": 6,
    "amount": "99620254"
  },
  "details": {
    "intentOutcomeRate": "999700000000000000",
    "protocolFee": "329910"
  },
  "build": {
    "srcToken": {
      "chainId": 42161,
      "token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
    },
    "dstToken": {
      "chainId": 8453,
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    },
    "amount": "100000000",
    "intentOutcomeRate": "999700000000000000",
    "terms": {
      "flatFee": "300000000000000000",
      "expiresAt": "1787000000",
      "signature": "0x60ce0a47bc64e07a5437de5fd4e6008bce46756d4d7c971710283924888b2a137a91ed09461b5848bb2b7341f5c258da3f97853e73662275f047e0c3c20882211b"
    }
  }
}

400

Section titled “400”

Invalid query (ValidationError), an unsupported token, or an exact_input size below the minimum (Error with detail.minSrcAmount).

Media typeapplication/json
Any of:

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 

{
  "error": "Requested amount is below what the solver will fill",
  "detail": {
    "minSrcAmount": "5000000"
  }
}

401

Section titled “401”

The X-API-Key header is missing.

Media typeapplication/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

Section titled “403”

The key is unknown or past its rotation window, or your integrator registry row is disabled or invalid. A 403 is always about your account: do not retry.

Media typeapplication/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"
}

404

Section titled “404”

Source and destination are the same asset.

Media typeapplication/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": "Source and destination resolve to the same mToken"
}

409

Section titled “409”

Larger than what can be filled now. Re-quote at detail.maxSrcAmount or detail.maxOutcomeAmount.

Media typeapplication/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": "Requested amount exceeds what the solver can fill",
  "detail": {
    "maxSrcAmount": "250000000000"
  }
}

429

Section titled “429”

Rate limited per integrator and per IP. No Retry-After; back off and retry.

Media typeapplication/json

Rate limited. No Retry-After; back off and retry.

object
errorCode
required
string
Allowed value: RATE_LIMITED
message
required
string

Example 

{
  "errorCode": "RATE_LIMITED",
  "message": "Too many requests, please retry later"
}

500

Section titled “500”

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

Media typeapplication/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"
}

503

Section titled “503”

Temporarily unavailable: your terms could not be read, a price or fee configuration is missing, or no solver can serve the direction (Error), or the API is in maintenance (NamedError with Retry-After). The variants cannot be told apart reliably, so cap your retries.

Media typeapplication/json
Any of:

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 

{
  "name": "MaintenanceException",
  "message": "SystemMaintenance"
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait. Sent only by the maintenance response.