> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/omniston/swap/v1beta8.md).

# 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](/developer-section/omniston/sdk/nodejs.md), [React](/developer-section/omniston/sdk/react.md), or [Direct API](/developer-section/omniston/swap.md) 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](/developer-section/omniston/glossary.md) for definitions and [Settlement lifecycle](/developer-section/omniston/how-omniston-works.md) for statuses, timing, partial fills, and secret disclosure.

## Shared references

* [Supported chains and assets](/developer-section/omniston/chains.md): chain IDs and asset addresses.
* [Environments and endpoints](/developer-section/omniston/environments.md): trading and History services.
* [Versions and migrations](/developer-section/omniston/migration.md): current support status and migration paths.

`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](/developer-section/omniston/referral-fees.md) 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](/developer-section/omniston/how-omniston-works.md) 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.                                                                         |

### Related fee and configuration fields

`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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ston.fi/developer-section/omniston/swap/v1beta8.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.