tx_create_json

Make transaction from a JSON description and place it in the mempool.

Note: This command creates and signs transactions on the RPC node. Public read-only nodes such as rpc.cellframe.net allow probing error responses but cannot create real transactions (no local wallet keys, no write access). Use a local node with wallets for actual transaction creation. The equivalent command mempool_add accepts the same -tx_obj / -json parameters.

JSON-RPC

Send a POST request to the node CLI JSON-RPC endpoint (for example POST http://rpc.cellframe.net/). Set method to tx_create_json.

Two request formats are supported (see index for full rules):

Version 1 — params array with one semicolon-separated CLI string.
Version 2 — omit params; use subcommand (usually empty) and arguments. Argument keys must not include a leading dash. Use string values; JSON booleans and numbers in arguments are rejected.

For RPC, prefer inline JSON via tx_obj (version 2) or -tx_obj (version 1). The json / -json option expects a file path on the node filesystem. The built-in help string only documents -json, but the handler also accepts -tx_obj (same as mempool_add).

Version 1 — params string

{
  "method": "tx_create_json",
  "params": ["tx_create_json;-net;Backbone;-chain;main;-tx_obj;{\"items\":[...]}"],
  "id": 1,
  "version": 1
}

Version 2 — subcommand + arguments

{
  "method": "tx_create_json",
  "subcommand": "",
  "arguments": {
    "net": "Backbone",
    "chain": "main",
    "tx_obj": "{\"items\":[...]}"
  },
  "id": 1,
  "version": 2
}

Command form

tx_create_json -net <net_name> [-chain <chain_name>] -json <json_file_path>
tx_create_json -net <net_name> [-chain <chain_name>] -tx_obj <json_string>

Parameters

Option	Description
`-net <net_name>`	Chain network. Can be omitted if `net` is set inside the JSON object.
`-chain <chain_name>`	Target chain. Can be omitted if `chain` is set in JSON; otherwise the default TX chain is used.
`-json <path>`	Path to a JSON file on the node.
`-tx_obj <string>`	Inline JSON object (recommended for RPC).

One of -json or -tx_obj is required.

JSON-RPC response envelope

tx_create_json is a JSON-response command:

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

type — 2 (TYPE_RESPONSE_JSON)
result — JSON array of result objects (or error objects)
id — echoes the request id
version — RPC protocol version

There is no top-level error field. Errors appear inside result as { "errors": [ { "code": <int>, "message": "<text>" } ] }. Partial item validation failures return a result object with tx_create: false instead of an errors wrapper.

Transaction JSON format

The JSON object must contain an items array. Optional top-level fields:

net — network name (if not passed via -net)
chain — chain name (if not passed via -chain)
ts_created — Unix timestamp (defaults to current time)

{
  "net": "Backbone",
  "chain": "main",
  "ts_created": 1783947227,
  "items": [
    {
      "type": "in",
      "prev_hash": "0xC7ECF43411E24509C240C6FC2003227AB930183719291555F658744C1FE46FF8",
      "out_prev_idx": 4
    },
    {
      "type": "out_std",
      "addr": "Rj7J7MiX2bWy8sNyZ43aVJB3RACsGwXbLrabvgAVEMr3vBVoqJy85nKTE5ghwytbymAbQCiLV1VparMcyKetuLx6TUhhbsSVN6zTY1me",
      "value": "1000000000000000000",
      "token": "CELL"
    },
    {
      "type": "sig",
      "sig_b64": "<base64_signature>",
      "sig_size": 2096
    }
  ]
}

Use mempool dump -tx_to_json on an existing mempool transaction to obtain a template in this format.

Supported item types

type	Key fields
`in`	`prev_hash`, `out_prev_idx`
`in_cond`	`prev_hash`, `out_prev_idx`, `receipt_idx`
`out`	`addr`, `value`
`out_std`	`addr`, `value`, `token`
`out_ext`	`addr`, `value`, `token` (required)
`out_cond`	`subtype` plus subtype-specific fields (e.g. srv_pay, srv_xchange, stake, wallet_shared)
`sig`	`sig_b64` (base64 signature), optional `sig_size`
`data`	`data_type`, `data` (base64 payload)
`event`	`group_name`, `event_type`, `service_id` or `service`
`receipt`	`service_id`, `price_unit`, `units`, `value`
`tsd`	Type-specific TSD payload fields

Values are in datoshi (uint256 string). Addresses are base58-encoded.

Examples

Error probe: missing JSON input (verified on rpc.cellframe.net)

Version 1:

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

Version 2:

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

Error probe: invalid JSON string

Version 1:

{
  "method": "tx_create_json",
  "params": ["tx_create_json;-net;Backbone;-tx_obj;{bad}"],
  "id": 2,
  "version": 1
}

Version 2:

{
  "method": "tx_create_json",
  "subcommand": "",
  "arguments": {"net": "Backbone", "tx_obj": "{bad}"},
  "id": 2,
  "version": 2
}

Create via inline JSON (local node with wallet)

Version 1:

{
  "method": "tx_create_json",
  "params": ["tx_create_json;-net;Backbone;-chain;main;-tx_obj;{\"items\":[{\"type\":\"in\",\"prev_hash\":\"0xABC...\",\"out_prev_idx\":0},{\"type\":\"out_std\",\"addr\":\"Rj7...\",\"value\":\"1000000000\",\"token\":\"CELL\"},{\"type\":\"sig\",\"sig_b64\":\"MEUCIQ...\"}]}"],
  "id": 3,
  "version": 1
}

Version 2:

{
  "method": "tx_create_json",
  "subcommand": "",
  "arguments": {
    "net": "Backbone",
    "chain": "main",
    "tx_obj": "{\"items\":[{\"type\":\"in\",\"prev_hash\":\"0xABC...\",\"out_prev_idx\":0},{\"type\":\"out_std\",\"addr\":\"Rj7...\",\"value\":\"1000000000\",\"token\":\"CELL\"},{\"type\":\"sig\",\"sig_b64\":\"MEUCIQ...\"}]}"
  },
  "id": 3,
  "version": 2
}

Create from file on node

Version 1:

{
  "method": "tx_create_json",
  "params": ["tx_create_json;-net;Backbone;-json;/opt/cellframe/tx.json"],
  "id": 4,
  "version": 1
}

Version 2:

{
  "method": "tx_create_json",
  "subcommand": "",
  "arguments": {"net": "Backbone", "json": "/opt/cellframe/tx.json"},
  "id": 4,
  "version": 2
}

Typical responses

Success

{
  "type": 2,
  "result": [
    {
      "tx_create": true,
      "hash": "0x1234...abcd",
      "total_items": 3
    }
  ],
  "id": 3,
  "version": 2
}

Partial validation failure

Some items could not be processed; transaction is not created.

{
  "type": 2,
  "result": [
    {
      "tx_create": false,
      "valid_items": 2,
      "total_items": 3,
      "errors": [
        "For item 2 of type 'out_std' the string representation of the address could not be converted, or the size of the output sum is 0."
      ]
    }
  ],
  "id": 3,
  "version": 2
}

Note: item-level validation errors are plain strings in the errors array, not {code, message} objects.

Command errors (verified on rpc.cellframe.net)

Missing -json / -tx_obj:

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 11, "message": "Command requires one of parameters '-json <json file path> or -tx_obj <string>'" }
      ]
    }
  ],
  "id": 1,
  "version": 2
}

Invalid JSON string:

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 12, "message": "Can't parse input JSON-string" }
      ]
    }
  ],
  "id": 2,
  "version": 2
}

Empty or invalid items array:

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 18, "message": "Can't create transaction from json file" }
      ]
    }
  ],
  "id": 2,
  "version": 2
}

Other possible errors (local node):

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 15, "message": "Not found net by name 'UnknownNet'" }
      ]
    }
  ],
  "id": 1,
  "version": 2
}

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 20, "message": "Can't add transaction to mempool" }
      ]
    }
  ],
  "id": 1,
  "version": 2
}

Related commands

mempool_add — same JSON input; alias for creating and adding to mempool
mempool dump -tx_to_json — export an existing mempool transaction as a JSON template
tx_create — create transaction via CLI flags instead of JSON
mempool list — verify the transaction appears in mempool
tx_history -tx — inspect transaction after it is accepted to chain
wallet outputs — list UTXOs to obtain prev_hash / out_prev_idx for in items