srv_xchange / srv_dex

Cellframe exposes two separate JSON-RPC methods for exchange services. They are registered independently in the node (dap_chain_net_srv_xchange.c and dap_chain_net_srv_dex.c) and are not RPC aliases of each other.

HTTP documentation for srv_dex is served from this page (srv_dex.html and dex.html map here in dap_cli_http_docs.c). That is a documentation redirect only; RPC calls must use the correct method name.

JSON-RPC request

Send POST to the CLI server (for example http://rpc.cellframe.net/). The top-level method names the module (srv_xchange or srv_dex). The HTTP body uses the Cellframe RPC envelope (type, result, id, version); the jsonrpc field is not used.

Two equivalent request shapes are supported (see dap_json_rpc_request_from_json and dap_json_rpc_params_create_from_subcmd_and_args):

Version 1 — `params` string

params is an array with one semicolon-separated string. Every token (module name, subcommand, flag, value) is separated by ;, not spaces. The string must start with the module name.

{"method":"srv_xchange","params":["srv_xchange;orders;-net;Backbone"],"id":1,"version":1}

{"method":"srv_dex","params":["srv_dex;pairs;-net;Backbone"],"id":1,"version":1}

Version 2 — `subcommand` and `arguments`

Omit params. Provide subcommand (string or JSON array for nested subcommands) and arguments (JSON object). Each key in arguments maps to a CLI flag -<key>; values are strings. Array values become comma-separated flag values (used for multi-value flags such as -orders).

{"method":"srv_xchange","subcommand":"orders","arguments":{"net":"Backbone"},"id":1,"version":2}

{"method":"srv_xchange","subcommand":["order","remove"],"arguments":{"net":"Backbone","order":"0x...","w":"mywallet","fee":"1000000000000000"},"id":1,"version":2}

{"method":"srv_dex","subcommand":"pairs","arguments":{"net":"Backbone"},"id":1,"version":2}

{"method":"srv_dex","subcommand":"orderbook","arguments":{"net":"Backbone","pair":"CELL/KEL"},"id":2,"version":2}

Verified live on rpc.cellframe.net (July 2026).

Response envelope

{
  "type": 2,
  "result": [ { ... } ],
  "id": 1,
  "version": 2
}

type 2 (TYPE_RESPONSE_JSON). Errors appear inside result as objects with an errors array (code, message). Use version 2 in requests for current snake_case field names in JSON responses.

Omitting subcommands or using a params string without the module prefix returns an error (verified: empty params for srv_xchange yields code 60, “Only 'order remove' and 'orders' are supported”).

Availability on rpc.cellframe.net

Verified live against http://rpc.cellframe.net/ (July 2026). Both methods are in allowed_cmd; they expose different command sets:

RPC method	Public node	Notes
`srv_xchange`	Legacy only	Only `orders` and `order remove`. All other legacy subcommands (`token_pair`, `tx_list`, etc.) are disabled in the handler (`#if 0` in `s_cli_srv_xchange`).
`srv_dex`	Full DEX v2	Query, analytics, trading, migration, and governance subcommands work on the public node. Write operations require a wallet on the node (`-w`) or unsigned mode (`-unsigned -addr`).

Do not call method: srv_dex expecting srv_xchange behaviour, or vice versa. Use srv_xchange;orders for legacy open-order listing and srv_dex;orders for the DEX v2 order book.

srv_xchange — legacy exchange (v1)

Handler: s_cli_srv_xchange in dap_chain_net_srv_xchange.c. Dispatches order / orders to s_cli_srv_xchange_order; any other subcommand returns code 60.

orders

srv_xchange orders -net <net_name> [-addr <seller_addr> | -seller <seller_addr>]

List open legacy (SRV_XCHANGE) orders. Omit -addr / -seller to list all open orders on the network.

RPC examples (public node):

{"method":"srv_xchange","params":["srv_xchange;orders;-net;Backbone"],"id":1,"version":1}

{"method":"srv_xchange","subcommand":"orders","arguments":{"net":"Backbone"},"id":1,"version":2}

Parameters:

-net — network name (required)
-addr / -seller — seller wallet address (optional)

JSON response (verified live):

// version 1
{ "orders": [ { ... } ], "number of orders": 283 }

// version 2
{ "orders": [ { ... } ], "total_orders": 283 }

Each element of orders contains:

order_hash — current tail transaction hash (hex)
order_root — root order hash (hex; equals order_hash when unchanged)
seller_addr — seller wallet address
pair — SELL/BUY ticker pair (e.g. CELL/mCELL)
sell_token, buy_token — tickers
rate — price string (buy per sell)
remain_coins, remain_datoshi — unfilled amount
availability — migrate or cancel_only

order remove

srv_xchange order remove -net <net_name> -order <order_hash> -w <wallet_name> -fee <value_datoshi>

Cancel a legacy order. Requires a wallet present on the node.

RPC examples:

{"method":"srv_xchange","params":["srv_xchange;order;remove;-net;Backbone;-order;0x...;-w;mywallet;-fee;1000000000000000"],"id":1,"version":1}

{"method":"srv_xchange","subcommand":["order","remove"],"arguments":{"net":"Backbone","order":"0x...","w":"mywallet","fee":"1000000000000000"},"id":1,"version":2}

Parameters (all required):

-net — network name
-w — wallet name on the node
-order — order transaction hash
-fee — transaction fee in datoshi

Validation order (live error probes): missing -net → code 22; missing -w → code 24; unknown wallet → code 25; missing -order → code 23; missing -fee → code 26.

Success response:

// version 1
{ "status": "...", "Created inactivate tx with hash": "0x...", "sign": "..." }

// version 2
{ "status": "success", "tx_hash": "0x...", "sign": "..." }

Not available via srv_xchange RPC

The following appear in older documentation or dead code but are not reachable through the current handler (return code 60):

order create, order history, order status
token_pair list|average|history
tx_list

Use srv_dex for DEX v2 order management and market data.

srv_dex — DEX v2

Handler: s_cli_srv_dex in dap_chain_net_srv_dex.c. Registered as a separate CLI/RPC command (dap_cli_server_cmd_add("srv_dex", ...)).

Available on rpc.cellframe.net for read and write subcommands. Query/analytics examples verified live: orders, orderbook, pairs, history, spread, purchase_auto -dry-run.

Set method to srv_dex. In v1, prefix the params string with srv_dex;. In v2, use subcommand / arguments (no params).

RPC examples (verified live):

{"method":"srv_dex","params":["srv_dex;pairs;-net;Backbone"],"id":1,"version":1}

{"method":"srv_dex","subcommand":"pairs","arguments":{"net":"Backbone"},"id":1,"version":2}

{"method":"srv_dex","subcommand":"orderbook","arguments":{"net":"Backbone","pair":"CELL/KEL"},"id":2,"version":2}

Order Management

srv_dex order create -net <net_name> -token_sell <ticker> -token_buy <ticker>
    (-w <wallet> | -unsigned -addr <addr>) -value <amount> -rate <price> -fee <fee>
    [-fill_policy AON|min|min_from_origin] [-min_fill_pct <0-100>] [-min_fill_value <amount>]

srv_dex order remove -net <net_name> -order <hash> (-w <wallet> | -unsigned -addr <addr>) -fee <fee>

srv_dex order update -net <net_name> -order <root_hash> (-w <wallet> | -unsigned -addr <addr>) -value <amount> -fee <fee>

Query

srv_dex orderbook -net <net_name> -pair <BASE/QUOTE>
    [-depth <N>] [-tick_price <step>] [-tick <decimals>] [-cumulative]

srv_dex orders -net <net_name> [-pair <BASE/QUOTE>] [-seller <addr>] [-limit <N>] [-offset <N>]

srv_dex pairs -net <net_name>

srv_dex status -net <net_name> -pair <BASE/QUOTE> [-seller <addr>]

srv_dex orders response fields (verified live, per order): pair, side (ASK/BID), root, tail, price, value_sell, locked_initial, filled_pct, min_fill_pct, min_fill_value, seller, ts, created.

Analytics

srv_dex find_matches -net <net_name> -order <hash> -addr <wallet_addr>

srv_dex history -net <net_name> [-pair <BASE/QUOTE> | -order <hash>] [-from <ts>] [-to <ts>] [-seller <addr>] [-buyer <addr>]
    [-view events|summary|ohlc|volume|stats]
      events (default):  [-type all|trade|market|targeted|order|update|cancel] [-limit <N>] [-offset <N>] [-tail]
      summary:           [-type all|trade|market|targeted|order|update|cancel] [-limit <N>] [-offset <N>] [-tail]
      ohlc:              [-type market|trade] [-bucket <sec>] [-fill]
      volume:            [-type market|targeted|trade] [-bucket <sec> [-fill]]
      stats:             [-type market|trade] (default range: last 1d if -from/-to omitted)
    Timestamp <ts>: unix | RFC822 (e.g. "01 Jan 2026 00:00:00 +0000") | now | -30m | -1h | -2d
    -tail: newest first (events|summary only)
    -fill without -bucket uses history_bucket_sec

srv_dex slippage -net <net_name> -pair <BASE/QUOTE>
    -value <amount> -side buy|sell -unit base|quote [-max_slippage_pct <pct>]

srv_dex spread -net <net_name> -pair <BASE/QUOTE> [-verbose]

srv_dex tvl -net <net_name> [-token <ticker>] [-by pair] [-top <N>]

Trading

srv_dex cancel_all_by_seller -net <net_name> -pair <BASE/QUOTE> -seller <addr> -side ask|bid
    (-w <wallet> | -unsigned -addr <addr>) -fee <fee> [-limit <N>] [-dry-run]

srv_dex purchase -net <net_name> -order <hash> (-w <wallet> [-addr <addr>] | -unsigned -addr <addr>) [-value <amount>] -fee <fee>
    [-unit sell|buy] [-create_leftover_order [-leftover_rate <rate>] [-leftover_fill_policy AON|min|min_from_origin]
    [-leftover_min_fill_pct <0-100>]]

srv_dex purchase_auto -net <net_name> -token_sell <ticker> -token_buy <ticker>
    execute: -value <amount> -fee <fee> (-w <wallet> [-addr <addr>] | -unsigned -addr <addr>)
    dry-run: -dry-run -addr <addr> -value <amount>
    [-unit sell|buy] [-rate_cap <price>] [-create_leftover_order [-leftover_rate <rate>]
    [-leftover_fill_policy AON|min|min_from_origin] [-leftover_min_fill_pct <0-100>]]

srv_dex purchase_multi -net <net_name> -orders <hash1,hash2,...> (-w <wallet> [-addr <addr>] | -unsigned -addr <addr>) -value <amount> -fee <fee>
    [-unit sell|buy] [-create_leftover_order [-leftover_rate <rate>] [-leftover_fill_policy AON|min|min_from_origin]
    [-leftover_min_fill_pct <0-100>]]

Migration

srv_dex migrate -net <net_name> -from <tx> -rate <price> -fee <fee> (-w <wallet> | -unsigned -addr <addr>)

Governance

srv_dex decree -net <net_name> -w <wallet> -service_key <cert> -fee <fee>
    -method fee_set|pair_add|pair_fee_set|pair_fee_set_all|pair_remove
      fee_set:          -fee_amount <amount> -fee_addr <addr>
      pair_add:         -token_base <ticker> -token_quote <ticker>
                        [-net_base <net>] [-net_quote <net>] [<fee_opt>]
      pair_fee_set:     -token_base <ticker> -token_quote <ticker>
                        [-net_base <net>] [-net_quote <net>] <fee_opt>
      pair_fee_set_all: <fee_opt>
      pair_remove:      -token_base <ticker> -token_quote <ticker>
                        [-net_base <net>] [-net_quote <net>]
    <fee_opt>: -fee_pct <pct> | -fee_native <amount> | -fee_config <byte>
               -fee_pct 2.0 = 2% of INPUT, -fee_native 0.05 = 0.05 native

CLI human-readable output

When using the local CLI client, append -h to format JSON-RPC results as tables. Add -full to show full hashes and addresses. This applies to both modules where supported.