Settlement integration

Settlement lets an approved executor use vault liquidity atomically: one token leaves the vault, the executor performs venue logic, and the expected token returns to the vault.

Flow

Discover vaults and assets through OMS registry endpoints, especially GET /registry/vaults.
Build and sign a settlement init request.
Submit POST /settlement/init.
Read the approval from the POST /settlement/init response, or fetch outstanding user signatures with GET /settlement/signatures/{user_id}.
Executor calls executeAtomicSettlement(...) on the vault.
Reconcile the vault Settled event and OMS inventory/account events.

Raw init

Settlement request amounts are hex integer strings without a 0x prefix. Use the live OMS reference for exact current wrappers. Populate signature with the Ed25519 signature bytes over compact inner before sending.

{
  "inner": {
    "tplus_user": "<user public key>",
    "sub_account_index": 1,
    "settler": "<settler public key>",
    "mode": "margin",
    "asset_in": "<32-byte token-in id>",
    "amount_in": "de0b6b3a7640000",
    "asset_out": "<32-byte token-out id>",
    "amount_out": "de0b6b3a7640000",
    "chain_id": "<chain id>"
  },
  "signature": [],
  "nonce": null,
  "additional_signers": []
}

If outer nonce is omitted or null, the backend selects the next managed settlement nonce for that (user, sub_account, chain). If you set one explicitly, it must not collide with an in-flight lock, and the single-settlement vault call requires the exact current (user, account) settlement counter.

tpluspy

from tplus.client import OrderBookClient
from tplus.model.settlement import InnerSettlementRequest, TxSettlementRequest

inner = InnerSettlementRequest.from_raw(
    tplus_user=user.public_key,
    sub_account_index=1,
    settler=settler.public_key,
    mode="margin",
    asset_in=asset_in_32,
    amount_in=10**18,
    decimals_in=18,
    asset_out=asset_out_32,
    amount_out=10**18,
    decimals_out=18,
    chain=chain_id,
)
request = TxSettlementRequest.create_signed(inner, user)

async with OrderBookClient("https://oms.tplus.cx", default_user=user) as oms:
    response = await oms._request(
        "POST",
        "/settlement/init",
        json_data=request.model_dump(mode="json", exclude_none=True),
    )
    approval = response["approval"]

Approval delivery

POST /settlement/init returns an approval object on success. GET /settlement/signatures/{user_id} returns outstanding approval signatures for that user. Use the REST response or the signatures endpoint as the public integration path. There is no public settlement-approval WebSocket route today.

Vault execution

The caller must be the executor registered for the settler id. The vault verifies expiry, settler approval, executor binding, nonce, and the CE approval signature, then increments the settlement nonce before the callback. It then calls the executor callback:

function onAtomicSettlement(address token, uint256 amount, bytes calldata data)
    external returns (uint256);

After the callback returns expectedAmountIn, the vault pulls tokenIn from the executor with transferFrom, then transfers tokenOut to the executor. The executor must approve the vault for at least the returned tokenIn amount before or during callback execution.

tokenIn.approve(address(vault), expectedAmountIn);
vault.executeAtomicSettlement(order, settler, data, signature);

Single atomic settlement is the available production flow. The vault ABI includes batch and squashing functions, but batch/squashing settlement is planned and not available through the public integration path today; use executeAtomicSettlement.

Getting Started

Integration guides

Settlement integration

Flow

Raw init

tpluspy

Approval delivery

Vault execution

​Flow

​Raw init

​tpluspy

​Approval delivery

​Vault execution

Flow

Raw init

tpluspy

Approval delivery

Vault execution