Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API model v1beta8

Current object relationships, settlement branches, raw order data, and fee fields.

stonfi.omni.v1beta8 is the current API namespace. This page describes the object model and settlement fields. Start implementing with the JS/TS, React, or Direct API guide.

Objects and settlement branches

RFQ → Quote → swap or order settlement. Swap settlement uses immediate routes. Order settlement creates an Order with Executions and positions; HTLC cross-chain flows also have destination-side positions and timed completion/rollback.

Check quote.settlementData.$case in SDK code. The chain names alone do not select the settlement method. Use the glossary for definitions and Settlement lifecycle for statuses, timing, partial fills, and secret disclosure.

Shared references

AssetId and ChainAddress are distinct stonfi.common.v1 types. Validate assets and addresses separately. Gasless quotes omit gas_budget and estimated_gas_consumption.

Amounts and fee fields

Amounts are integer asset-unit strings. input_units is the input paid by the trader; output_units is the trader's net output. integrator_fee_units and protocol_fee_units are output-asset fee amounts. For order settlement, resolver_sends_units is the trader's net output plus protocol and integrator fees.

SDK properties use camelCase (inputUnits, outputUnits, integratorFeeUnits). See Integrator fees for RFQ rate configuration; rate values and asset amounts are different units.

How to Read Raw Settlement Data

OrderSettlementData contains the protocol contract addresses, deadlines, and HTLC parameters for order settlement. The JSON-RPC API uses snake_case; the SDK exposes the corresponding camelCase properties. HTLC fields apply to cross-chain settlement.

See Settlement lifecycle for execution phases and timing.

Common OrderSettlementData Fields

Raw field
Meaning

src_protocol_contract_address / srcProtocolContractAddress

Protocol contract that enforces settlement on the Source blockchain.

src_wrapped_native_token_address / srcWrappedNativeTokenAddress

Wrapper contract for the Input asset when that asset is native on the source chain, such as pTON or wETH. Omitted when the input asset is not native.

src_initial_resolver_address / srcInitialResolverAddress

Resolver wallet on the Source blockchain for which the position is initially reserved during the exclusivity window. Omitted for positions created without an exclusive reservation.

src_htlc_security_deposit_asset / srcHtlcSecurityDepositAsset

HTLC-only asset used for the source-side security deposit.

src_htlc_security_deposit_units / srcHtlcSecurityDepositUnits

HTLC-only amount of the source-side security deposit, denominated in src_htlc_security_deposit_asset.

htlc_hashing_function / htlcHashingFunction

HTLC-only hashing function used to generate secret hashes, including trader-provided hashes.

dst_protocol_contract_address / dstProtocolContractAddress

HTLC-only protocol contract on the Destination blockchain that enforces the output-side leg.

resolver_sends_units / resolverSendsUnits

Total Output asset sent by the resolver: the trader's net output_units plus protocol and integrator fees.

dst_wrapped_native_token_address / dstWrappedNativeTokenAddress

Wrapper contract for the Output asset when that asset is native on the destination chain. Omitted when the output asset is not native.

dst_security_deposit_asset / dstSecurityDepositAsset

HTLC-only asset used for the destination-side security deposit.

dst_security_deposit_units / dstSecurityDepositUnits

HTLC-only amount of the destination-side security deposit, denominated in dst_security_deposit_asset.

trade_start_deadline / tradeStartDeadline

Latest UTC timestamp for funds to reach the source-side protocol contract or for order signing. Settlement after this deadline is at the resolver's discretion.

exclusivity_timeout / exclusivityTimeout

Maximum duration from trader position creation to resolver reservation, including the required security deposit.

OrderSettlementData also contains these fee fields:

  • integrator_fee_pips / integratorFeePips: integrator fee rate copied from the RFQ. One pip is 1/1,000,000 or 0.0001%.

  • protocol_fee_pips / protocolFeePips: protocol fee rate copied from the resolver protocol parameters. The fee is collected in the Output asset.

  • protocol_fee_recipient_address / protocolFeeRecipientAddress: optional destination-chain address receiving the protocol fee.

Last updated