wallet

Wallet operations — create, list, inspect balances, manage outputs, and shared-funds workflows.

Verified against public RPC http://rpc.cellframe.net/ (networks: Backbone, KelVPN, 2026-07-14). Address-based read-only queries (info -addr, outputs, shared ledger lookups) work against the public ledger. Subcommands that create or open .dwallet files act on the RPC node’s wallet directory — they can succeed on a public node and mutate shared state; prefer your own node for write workflows.

JSON-RPC request

Method name: wallet. Response type is 2 (TYPE_RESPONSE_JSON). Two request formats are supported; if params is present, the version 2 path is ignored.

Version 1 — legacy `params` string

{"method":"wallet","params":["wallet;list"],"id":1,"version":1}

{"method":"wallet","params":["wallet;info;-addr;ADDR"],"id":2,"version":1}

params is an array with one string. Every token (command, subcommand, flag, value) is separated by ; — not spaces.

Version 2 — `subcommand` + `arguments`

{"method":"wallet","subcommand":"list","id":1,"version":2}

{"method":"wallet","subcommand":"info","arguments":{"addr":"ADDR"},"id":2,"version":2}

subcommand may also be a JSON array for multi-token subcommands:

{"method":"wallet","subcommand":["shared","list"],"arguments":{"net":"Backbone"},"id":5,"version":2}

Equivalent string form: "subcommand":"shared;list". Both produce wallet;shared;list;-net;Backbone internally.

Version 2 `arguments` rules

Keys map to CLI flags without a leading dash (addr → -addr).
Values must be strings (or null / "" for bare flags such as verbose or local). JSON numbers and booleans are rejected.
Comma-separated CLI values stay in one string (e.g. "pkey_hashes": "0xHASH1,0xHASH2").
Array values in arguments expand to comma-separated tokens (see dap_json_rpc_params_create_from_subcmd_and_args).

Common `arguments` keys

`arguments` key	CLI flag	Used by
`w`	`-w`	`info`, `outputs`, `new`, `activate`, shared write ops
`addr`	`-addr`	`info`, `outputs`, `find`, shared ops
`net`	`-net`	`info` (with `-w`), `outputs` (with `-w`), shared ops
`token`	`-token`	`outputs`, `shared hold`
`value`, `fee`	`-value`, `-fee`	Shared write ops
`verbose`	`-verbose`	Any subcommand (bare flag: `""`)
`H`	`-H`	Shared ops (`hex` or `base58`)

Params / CLI syntax (v1 reference)

wallet;list
wallet;info;-addr;Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33
wallet;info;-w;mywallet;-net;Backbone
wallet;outputs;-addr;Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33;-token;CELL
wallet;find;-addr;Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33
wallet;shared;list;-net;Backbone
wallet;shared;info;-net;Backbone;-addr;rTDbDhvpdG11HLCMQQDVUyxJQP4Gxjd4n47SnASRZta1xs6AQbkQ4vpGsSHUHXEhBqzmJhev7o93NSSjhiPBcJC1g9ERzZBuZSiXzcSs

JSON-RPC response

Envelope (verified on rpc.cellframe.net):

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

On error, result contains one or more objects with an errors array:

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 3, "message": "Couldn't find any wallets" }
      ]
    }
  ],
  "id": 1,
  "version": 1
}

Some subcommands (info, outputs, list, find, …) wrap their payload in an inner JSON array, so success may look like "result": [[{...}]]. Shared subcommands (shared info, shared list, …) return flat objects directly in result.

Add -verbose (v1 params) or "verbose": "" (v2 arguments) to append a ret_code object to the response.

v1 vs v2 response field names

The response version echoes the request. Most wallet fields are identical; one known difference in outputs per-UTXO objects:

Field	version 1	version 2
Per-output datoshi amount	`value_datosi`	`value_datoshi`

Totals always use total_value_datoshi in both versions.

Subcommands reference

Subcommand	RPC on public node	Required params	Optional params
`list`	Yes (returns empty-wallets error)	—	—
`info`	Yes with `-addr`	Exactly one of `-addr` or `-w`. With `-w`: also `-net`	`-net` (ignored when `-addr` is used; network is taken from the address)
`outputs`	Yes with `-addr`	Exactly one of `-addr` or `-w`; `-token`. With `-w`: also `-net`	`-cond`, `-type <cond_type>`, `-value <uint256>`, `-mempool_check`
`find`	Yes (returns `not found` on public node)	`-addr`	`-file <wallet_dir>`
`new`	Writes to node wallet dir	`-w <wallet_name>` (alphanumeric only)	`-sign <sign_type>`, `-restore <hex>`, `-restore_legacy <hex>`, `-net`, `-force`, `-password`
`activate`	Writes to node wallet dir	`-w`, `-password`	`-ttl <minutes>` (default 60)
`deactivate`	Writes to node wallet dir	`-w`	—
`convert`	Writes to node wallet dir	`-w`; exactly one of `-password` or `-remove_password`	—
`shared hold`	Writes to node wallet dir	`-net`, `-w`, `-token`, `-value`, `-fee`, `-signs_minimum`; at least one of `-pkey_hashes` or `-addrs`	`-tag`, `-H hex\|base58`
`shared refill`	Writes to node wallet dir	`-net`, `-w`, `-value`, `-fee`; exactly one of `-tx` or `-addr` (shared address)	`-H hex\|base58`
`shared take`	Writes to node wallet dir	`-net`, `-w`, `-fee`, `-value`, `-to_addr`; exactly one of `-tx` or `-addr`	`-H hex\|base58`. `-to_addr` and `-value` are comma-separated lists of equal length
`shared sign`	Writes to node wallet dir	`-net`, `-tx`; exactly one of `-w` or `-cert`	`-H hex\|base58`
`shared info`	Yes	`-net`; exactly one of `-tx` or `-addr` (shared address)	`-H hex\|base58`
`shared history`	Yes	Exactly one of `-tx` or `-addr`	`-net` (required with `-tx`; auto-detected from `-addr`), `-H hex\|base58`
`shared list`	Yes	—	`-net`, `-pkey`, `-addr`, `-w`, `-cert` (mutually exclusive filters), `-local`, `-verbose`, `-H hex\|base58`

Conditional output types for outputs -type: srv_pay, srv_xchange, srv_stake_pos_delegate, srv_stake_lock, fee.

Example requests (verified on rpc.cellframe.net)

list

List wallet files stored on the RPC node. When the wallet directory is empty, the response is an error object; when wallets exist, each entry includes Wallet, status, deprecated, and signs.

{"method":"wallet","params":["wallet;list"],"id":1,"version":1}

{"method":"wallet","subcommand":"list","id":1,"version":2}

Empty directory:

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 3, "message": "Couldn't find any wallets" }
      ]
    },
    []
  ],
  "id": 1,
  "version": 1
}

With a wallet present (example from a public node after wallet new):

{
  "type": 2,
  "result": [
    [
      {
        "Wallet": "testwallet.dwallet",
        "status": "unprotected",
        "deprecated": "false",
        "signs": "sig_dil"
      }
    ]
  ],
  "id": 1,
  "version": 1
}

info

Address balances and metadata. Use -addr on public RPC; use -w -net only on a node that stores the wallet file.

{"method":"wallet","params":["wallet;info;-addr;Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33"],"id":2,"version":1}

{"method":"wallet","subcommand":"info","arguments":{"addr":"Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33"},"id":2,"version":2}

{
  "type": 2,
  "result": [
    [
      {
        "addr": "Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33",
        "pkey_hash": "0xAE6D3B53F6896592857BD17D65ADFA54CEA2B5D5963DAFFA9460763D1DB93EF8",
        "network": "Backbone",
        "signs": "sig_dil",
        "tokens": [
          {
            "balance": "",
            "coins": "3.0",
            "datoshi": "3000000000000000000",
            "token": { "ticker": "CELL", "description": null }
          }
        ]
      }
    ]
  ],
  "id": 2,
  "version": 2
}

Missing -addr/-w:

{ "code": 2, "message": "You should use either the -w or -addr option for the wallet info command." }

With -w on a node without that wallet:

{ "code": 3, "message": "Wallet not found or addr not recognized" }

outputs

List spendable UTXOs for an address and token.

{"method":"wallet","params":["wallet;outputs;-addr;Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33;-token;CELL"],"id":3,"version":1}

{"method":"wallet","subcommand":"outputs","arguments":{"addr":"Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33","token":"CELL"},"id":3,"version":2}

Version 1 response (note value_datosi on each UTXO):

{
  "type": 2,
  "result": [
    [
      {
        "wallet_addr": "Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33",
        "total_value_coins": "3.0",
        "total_value_datoshi": "3000000000000000000",
        "outs": [
          {
            "item_type": "unspent_out",
            "value_coins": "3.0",
            "value_datosi": "3000000000000000000",
            "prev_hash": "0x36B659A1FD88B4BE47D984596DE7A5C36D594D7DEE41FED20572DD5BD3778343",
            "out_prev_idx": 0
          }
        ]
      }
    ]
  ],
  "id": 3,
  "version": 1
}

Version 2 response uses value_datoshi instead of value_datosi on each UTXO; totals are unchanged.

Missing -token:

{ "code": 1, "message": "Subcommand outputs requires parameter '-token'" }

find

Find local wallet filename(s) matching an address. Scans node wallet directory only.

{"method":"wallet","params":["wallet;find;-addr;Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33"],"id":4,"version":1}

{"method":"wallet","subcommand":"find","arguments":{"addr":"Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33"},"id":4,"version":2}

{
  "type": 2,
  "result": [
    [
      { "status": "not found" }
    ]
  ],
  "id": 4,
  "version": 2
}

Missing -addr:

{ "code": 8, "message": "You should use -addr option for the wallet find command." }

shared list

{"method":"wallet","params":["wallet;shared;list;-net;Backbone"],"id":5,"version":1}

{"method":"wallet","subcommand":"shared;list","arguments":{"net":"Backbone"},"id":5,"version":2}

{"method":"wallet","subcommand":["shared","list"],"arguments":{"net":"Backbone"},"id":6,"version":2}

Returns one object per public-key hash with pkey_hash, optional addr, tx_hashes, shared_wallets, member_of. The unfiltered list can be very large; use -net to narrow results. Use -verbose / "verbose": "" for balances, tx_hash_final, owner hashes, and pending operations (may be slow on public nodes).

shared info

{"method":"wallet","params":["wallet;shared;info;-net;Backbone;-addr;rTDbDhvpdG11HLCMQQDVUyxJQP4Gxjd4n47SnASRZta1xs6AQbkQ4vpGsSHUHXEhBqzmJhev7o93NSSjhiPBcJC1g9ERzZBuZSiXzcSs"],"id":6,"version":1}

{"method":"wallet","subcommand":["shared","info"],"arguments":{"net":"Backbone","addr":"rTDbDhvpdG11HLCMQQDVUyxJQP4Gxjd4n47SnASRZta1xs6AQbkQ4vpGsSHUHXEhBqzmJhev7o93NSSjhiPBcJC1g9ERzZBuZSiXzcSs"},"id":6,"version":2}

{
  "type": 2,
  "result": [
    {
      "addr": "rTDbDhvpdG11HLCMQQDVUyxJQP4Gxjd4n47SnASRZta1xs6AQbkQ4vpGsSHUHXEhBqzmJhev7o93NSSjhiPBcJC1g9ERzZBuZSiXzcSs",
      "tx_hash": "0x8F78328520CA9AE5D6BD004CD9C040C912AB85D5AA47F530B5EBC500DAB47391",
      "tx_hash_final": "0x78C9E1889C6AFFE961417C6EA2257747569FAC972D9110F95A326E7392870C1A",
      "tags": [],
      "balance": { "coins": "0.2", "datoshi": "200000000000000000" },
      "token": { "ticker": "CELL", "description": null },
      "creator": "0xDE63054AE7E914960AA24DCDFA40E29394B4FDE55372724D24E98FB9896D6832",
      "creator_addr": "Rj7J7MiX2bWy8sNyb2aqPVS6dadJxWe9bLg3vKk5Vvh7BgUe7UXs1yZH4qeDaC5eGz4umS63CNP8jKwYeSUKBpcKPDbfbeF7kRVizDDZ",
      "take_verify": {
        "signs_minimum": 2,
        "owner_hashes": ["0xDE63054AE7E914960AA24DCDFA40E29394B4FDE55372724D24E98FB9896D6832", "..."]
      },
      "waiting_operations_count": 0,
      "waiting_operations_hashes": []
    }
  ],
  "id": 6,
  "version": 2
}

Missing -tx/-addr:

{ "code": 3, "message": "Parameter -tx or -addr is required" }

shared history

{"method":"wallet","params":["wallet;shared;history;-addr;rTDbDhvpdG11HLCMQQDVUyxJQP4Gxjd4n47SnASRZta1xs6AQbkQ4vpGsSHUHXEhBqzmJhev7o93NSSjhiPBcJC1g9ERzZBuZSiXzcSs"],"id":7,"version":1}

{"method":"wallet","subcommand":["shared","history"],"arguments":{"addr":"rTDbDhvpdG11HLCMQQDVUyxJQP4Gxjd4n47SnASRZta1xs6AQbkQ4vpGsSHUHXEhBqzmJhev7o93NSSjhiPBcJC1g9ERzZBuZSiXzcSs"},"id":7,"version":2}

Returns hold_tx, addr, and an operations array (hold, take, …) with signers and values.

Write operations (node wallet directory)

These subcommands create, unlock, or sign with .dwallet files under the RPC node’s wallet path. They can succeed on public RPC (verified: wallet new created a wallet on rpc.cellframe.net) and therefore affect shared node state. Prefer your own node for any write workflow.

new

{"method":"wallet","params":["wallet;new;-w;mywallet;-net;Backbone"],"id":10,"version":1}

{"method":"wallet","subcommand":"new","arguments":{"w":"mywallet","net":"Backbone"},"id":10,"version":2}

Success fields: wallet_name, sig_type, status, optional new_addr when -net is given.

activate / deactivate

{"method":"wallet","params":["wallet;activate;-w;mywallet;-password;secret;-ttl;60"],"id":11,"version":1}

{"method":"wallet","subcommand":"activate","arguments":{"w":"mywallet","password":"secret","ttl":"60"},"id":11,"version":2}

{"method":"wallet","subcommand":"deactivate","arguments":{"w":"mywallet"},"id":12,"version":2}

convert

{"method":"wallet","params":["wallet;convert;-w;mywallet;-password;newsecret"],"id":13,"version":1}

{"method":"wallet","subcommand":"convert","arguments":{"w":"mywallet","password":"newsecret"},"id":13,"version":2}

{"method":"wallet","subcommand":"convert","arguments":{"w":"mywallet","remove_password":""},"id":14,"version":2}

shared hold (create multisig hold tx)

{"method":"wallet","params":["wallet;shared;hold;-net;Backbone;-w;mywallet;-token;CELL;-value;1.0;-fee;0.05;-signs_minimum;2;-pkey_hashes;0xHASH1,0xHASH2;-addrs;Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33"],"id":20,"version":1}

{"method":"wallet","subcommand":["shared","hold"],"arguments":{"net":"Backbone","w":"mywallet","token":"CELL","value":"1.0","fee":"0.05","signs_minimum":"2","pkey_hashes":"0xHASH1,0xHASH2","addrs":"Rj7J7MiX2bWy8sNya4yB7z86JReYjFyAjK94mmyjQmabzKSZMpimaQkwa1D139gYbBA5mmkrxRVCxVq68AxCejZZuoWWrKWiCGiDpQ33"},"id":20,"version":2}

Success: status, tx_hash, addr (shared address).

shared refill / take / sign

{"method":"wallet","subcommand":["shared","refill"],"arguments":{"net":"Backbone","w":"mywallet","value":"1.0","fee":"0.05","tx":"0xHOLD_HASH"},"id":21,"version":2}

{"method":"wallet","subcommand":["shared","take"],"arguments":{"net":"Backbone","w":"mywallet","tx":"0xHOLD_HASH","to_addr":"ADDR1","value":"0.5","fee":"0.05"},"id":22,"version":2}

{"method":"wallet","subcommand":["shared","sign"],"arguments":{"net":"Backbone","w":"mywallet","tx":"0xDEBIT_TX_HASH"},"id":23,"version":2}

Value format hints

value_coins (natural numbers): e.g. 1.0, 123.4567
value_datoshi (integer): e.g. 1, 20, 0.4321e+4

Common error codes

Code	Typical cause
1	Missing or invalid parameter (`-token`, command format, …)
2	Missing/ambiguous `-w`/`-addr`; invalid wallet name characters
3	No wallets on node; wallet/address not found
6	Unknown `-net` name; `-net` required with `-w`
8	Invalid or missing address (`find`)
9	Wallet name already exists (`new`)