API

Overview

TrexWallet provides REST APIs for user sessions, merchants, trusted services, and scanners:

• Response format: ApiResponse<T> with result, error, and id fields
• Authentication: Session authentication for user APIs, merchant credentials for /payorders/v1/, and deployment-issued service credentials for private APIs
• IDs: 64-bit identifiers; send and store them as decimal strings in JavaScript clients

API Documentation (Swagger)

You can access TrexWallet's API Reference (Swagger) in several demo projects (note, that you need to login/register in these demo apps to get to Swagger):

• demo wallet
• demo corporate chat

Alternatively, you can create your own demo project and use itbuild.app's dev-environment as a playground.

Key API Endpoints

Category	Base URL	Description
Trex	/trex/v1/[action]	Assets, transfer codes, candles
Wallet	/trex/v1/wallet/[action]	Balances, transfers, history
Market	/trex/v1/market/[action]	Rates, orders, swap, rooms
Investments	/trex/v1/invest/[action]	Investment products
Payment Orders	/payorders/v1/[action]	Merchant H2H: put_payment_order, put_transfer_order, get_app_payments, wait_app_payment, refund_payment
Payment Gate	/payment/v1/[action]	Universal /pay page: get_order_info, get_terminals, order_start (alias payment_order_start), pay_transfer, built-in pay_*
Private	/private/v1/[action]	Trusted service and scanner integrations
Monitoring	Private monitoring interface	Runtime and scanner health metrics

Endpoint Catalog

The authoritative, always-current contract is the running Swagger (/trex/swagger/). Session endpoints resolve the caller from the authenticated session. Merchant endpoints use merchant credentials and app_id; private/scanner endpoints use deployment-issued service credentials.

Wallet — session (/trex/v1/wallet/)

Action	Method	Purpose
get_info	GET	Wallet metadata + sibling wallets
update_settings	POST	Name / sort order / default flag
get_balance	GET	Sub-balances per currency
create_address	GET	Generate deposit address for a token network
list_addresses	GET	Deposit addresses (includeTechnicalState optional)
internal_transfer	POST	Internal transfer (2-step OTP/2FA); recipient may be a contact/internal address or an exact destination wallet_id for self wallet transfers
create_withdraw	POST	External withdrawal (2-step)
cancel_tx	POST	Canonical cancellation: pass exactly one query parameter, code or id
cancel_withdraw	POST	Obsolete Outcome-only alias of cancel_tx (timetick)
set_security	POST	Toggle per-wallet require2FA
get_tx_info	GET	Single transaction by id/code
get_tx_list_info	POST	Batch tx details (≤100 ids)
get_history_transactions	GET	History with filters (limit ≤1000)
get_profit_transactions	GET	Profit payout rows where this wallet is profit_acc (fee > expense)
list_txs_awaiting_partner_info	GET	Active Income rows that require partner_info (limit 1–100)
init_refund	POST	User-initiated outer refund
get_federation_partners	GET	Federation partners list
create_partner_order	POST	Cross-project pay order + URL
create_partner_transfer	POST	Cross-project transfer out
cancel_partner_transfer	POST	Cancel pending federation out (timetick)
update_tx_partner_info	POST	Seal partner_info on an income

General — session (/trex/v1/)

Action	Method	Purpose
tokens_networks	GET	Top-up/withdraw terminals (WalletTerminalOut[])
assets	GET	Currency catalog
estimate_fee	GET	Fee preview by tx_type
my_payment_stats	GET	Daily summaries for one owned merchant app (appId required; optional UTC from/to)
apply_code	POST	Apply transfer/room/invoice code
cancel_code	POST	Obsolete transfer-code alias of /trex/v1/wallet/cancel_tx
create_tx_code	POST	Create a transfer code
invest_tx_info	POST	Investment-linked tx details (body: id array)
order_tx_info	POST	Order-linked tx details (body: id array)
address_tx_info	POST	On-chain tx details (body: id array)
get_info / get_candles	GET	Public health / OHLC data

address_tx_info returns requirePartnerInfo from the selected terminal. Use it with list_txs_awaiting_partner_info: the list is the narrow Income queue for the authenticated wallet, while address_tx_info supplies the per-terminal flag used to render the partner-info form.

Gapless wallet history polling

For incremental module consumers, call get_history_transactions with orderByUpdate=true and oldestFirst=true. Use startTick as the inclusive lower timetick_update bound and endTick as the exclusive upper bound. Keep endTick fixed for the scan and, after each successful page, set startTick to the greatest returned idUpdate plus one. Send and store startTick, endTick, transaction IDs, and update ticks as decimal strings: they are int64 values and must not pass through JavaScript number.

Market — session (/trex/v1/market/)

Action	Method	Purpose
get_rates	GET	Exchange rates (to, optional from[])
get_trade_info	GET	Order book depth (room_key)
get_orders	GET	User orders (room_key)
create_order	POST	Create limit/market order
cancel_order	POST	Cancel order (id)
list_rooms	GET	Private rooms
create_room	POST	Create room
close_room	POST	Close/leave room (roomId)
create_swap	POST	Atomic swap (2-step)
swap_info	GET	Swap limits/rates

Investments — session (/trex/v1/invest/)

Action	Method	Purpose
get_investments	GET	List investments
get_investment_info	GET	Investment detail
return_investment	POST	Early close request (investment)

Payment Gate — no auth, by order code (/payment/v1/)

Action	Method	Purpose
get_order_info	GET	Public order info (PaymentOrder or TransferOrder by code)
get_terminals	GET	Terminal list (TerminalOut[])
order_start	POST	Lock terminal + tariff (type-agnostic). Legacy alias: payment_order_start
pay_transfer	POST	TransferOrder phase 2b: recipient + meta → dispatch
pay_crypto	POST	Crypto deposit details (tokenNetworkId)
confirm_crypto	POST	Bind tx_hash
cancel_crypto	POST	Cancel crypto payment
pay_card	POST	Built-in acquiring session (tokenNetworkId)
pay_internal	POST	Pay from wallet (session)

Merchant — pkey + app_id (/payorders/v1/)

Action	Method	Purpose
put_payment_order	POST	Create payment order
put_transfer_order	POST	Create outgoing transfer (payout) order
get_app_payments	GET	Forward app payment change-feed (cursor; up to 100 rows)
wait_app_payment	GET	Long-poll the app payment change-feed (cursor; up to 100 rows)
get_app_payment	GET	Single payment
refund_payment	POST	Merchant refund
get_refund_status	GET	Refund status

wait_app_payment returns HTTP 200 as soon as matching rows exist after cursor. If no matching payment arrives before the server-side long-poll timeout, it returns HTTP 202 with an empty result. Both responses carry the next watermark in ApiResponse.cursor. Use a client timeout above 50 seconds.

Private S2S + scanner (/private/v1/)

These integration endpoints require deployment-issued service credentials. Reference data (currencys, tokens_networks, get_wallets, wallet_info_get, get_rate/get_rates, swap_info), ledger (transact_get, list_last_updated_txs, wait_cursor, execute_transactions, link_address_transactions), wallet lifecycle (create_wallet, update_wallet), payment (create_payment_order, create_acquiring_order, get_payment_order_info, get_payment_terminals, payment_stat_get, pending_acquiring_txs), federation (federation_credit), governance (create_debt_charge), event polling (events), monitoring (monitoring_stats), and scanner operations (tx_list_push, list_txs_to_send, address_block_list). Scanner blocks use tx_list_push(AddressTxBatch); the legacy income_push_block endpoint is removed.

POST /private/v1/list_last_updated_txs accepts:

{
  "since": 0,
  "limit": 100,
  "scope": 0,
  "networks": [],
  "tokenNetworks": [],
  "intern": null
}

since is the exclusive journal cursor; limit is clamped to 1–1000; scope is 0 (Both), 1 (Client), or 2 (Address). networks expands network-type enum values to their terminal IDs, tokenNetworks filters by terminal ID directly, and intern filters the money side by app/merchant ID. The response watermark is ApiResponse.cursor.

GET /private/v1/wait_cursor?cursor={cursor} long-polls the module-wide committed transaction watermark. It returns HTTP 200 immediately when the committed cursor is greater than the supplied value, or HTTP 202 after an idle wait. The current watermark is always returned in ApiResponse.cursor. This endpoint only signals that the change-feed moved; read the rows through list_last_updated_txs.

Updating a wallet (update_wallet)

Trusted services change wallet attributes — including the tariff/network group (wallet_group, 0..63) — through POST /private/v1/update_wallet with a TrexWalletInfo body.

TrexWalletInfo(id, client_id, timetick_update, flags, wallet_group, project, max_addr_count, name, sort_order)

• Null means "leave unchanged". Send id plus only the fields you want to change; pass null for everything else.
• client_id — the owner is immutable: it is ignored on write (a wallet cannot be reassigned to another client via update_wallet) and is only populated on the get_info response.
• wallet_group (byte?) — tariff/network group. Sending 5 sets the group; null keeps it.
• flags (wallet_info_flags?) — null leaves flags untouched. When supplied, the module reconciles the single-IsDefault-wallet-per-owner invariant.
• timetick_update (long?) — server-authoritative: the change marker is generated inside the module on every update and any request value is ignored. Send null on write; it is populated only on the get_info response as the synchronization version.
• name / sort_order / max_addr_count / project — null keeps the current value.

Updating a network (update_network)

add_network creates a terminal (all fields authoritative); update_network patches an existing terminal by id with a TerminalIn body. Identity fields (typeNetwork, typeContract, currencyId, decimals, addressContract) and scanner-managed fields (last_block, …) are preserved. Optional attributes (name, tag, priority, networkFee, …) are nullable: null = keep, ""/0 = clear. flags, defaultHotAddress, defaultSystemWalletId and walletGroups are always written — send their current values on update.

Response Format

result is endpoint-specific. For example, GET /trex/v1/wallet/get_balance returns a list of per-currency sub-balances (GetBalanceOut[]):

{
  "result": [
    {
      "currency": "USDT",
      "freeBalance": 1000.50,
      "lockOutBalance": 0,
      "lockInBalance": 0,
      "lockOrders": 0,
      "userBalance": 1000.50,
      "userBalanceBaseEqu": 920.10
    }
  ],
  "error": null,
  "id": 0
}

Error Response

{
  "result": null,
  "error": {
    "code": 10002,
    "message": "Balance not enough"
  },
  "id": 0
}

Integration boundaries

Merchant systems use /payorders/v1/; authenticated wallet applications use /trex/v1/; trusted services and scanners use /private/v1/. Custom provider integrations own their provider-specific UI and API calls, then report outcomes through the documented TrexWallet contract. TrexWallet remains responsible for order lifecycle, tariff application, balances, and final transaction status.

Payment Gateway

TrexWallet owns payment order state, tariff application, balances, and built-in payment methods. For a custom terminal, the merchant integration owns provider-specific processing and reports the outcome through the integration API. The universal payment page is /pay.

Payment methods

Method	How it works	Merchant integration required?
CardAcquiring (built-in)	Stripe / T-Bank checkout through built-in card acquiring	No
CardAcquiring (custom)	Merchant continuation via terminal flow path	Yes
CryptoTransfer	On-chain payment to the address issued for the order	No
InternalPayment	Pay from caller's existing wallet balance	No
P2PTransfer (custom)	Merchant continuation via flow_path (custom P2P provider)	Yes
BankWireTransfer	Merchant continuation via flow_path (no built-in pay_wire)	Yes

Payment flow

1. Merchant creates a payment order and receives a payment code.
2. Payer opens /pay?code=....
3. TrexWallet shows eligible terminals.
4. Payer selects a terminal.
5. TrexWallet applies tariff and locks the order to that terminal.
6. Built-in methods render a built-in widget; custom methods redirect to merchant continuation.
7. TrexWallet records the final status after provider or scanner confirmation.

See Payment Gateway processes for the full integration flow.

Payment Statistics

GET /trex/v1/my_payment_stats returns one summary per UTC day, currency, and transaction type for an app owned by the authenticated user. appId is required. from and to are optional inclusive UTC calendar dates; the default is seven days ending today, and the maximum range is 366 days.

GET /private/v1/payment_stat_get exposes the same daily contract to trusted services. Its optional appId filters one app; when omitted, rows for all apps are returned. It uses the same UTC date defaults and 366-day cap.

Rows contain appId, dayNumber, day, currency, txType, total, finished, and amountFinished. IDs, cursors, and timeticks are serialized as strings where exposed to JavaScript consumers.

Private API: transact_get

GET /private/v1/transact_get?timetick=... performs a single transaction lookup by timetick. Historical transactions are supported. The endpoint has no activeOnly request mode. A missing transaction returns null.