RPC Interfaces

RPCs

The chia node and services come with a JSON rpc api server that allows you to access information and control the services. These are accessible via HTTP, WebSockets, or a python client. The ports can be configured in ~/.chia/mainnet/config/config.yaml. The rpc ports should not be exposed to the internet.

Default Ports:

• Daemon: 55400
• Full Node: 8555
• Farmer: 8559
• Havester: 8560
• Wallet: 9256

HTTP/JSON

The certificates must be used when calling the RPCs from the command line, make sure to use the correct certificates for the services you are calling. All endpoints are made with POST with JSON data. The response is a JSON dictionary with a success field, which can be true or false.

WebSockets

If you are using the Websockets API, you can go directly through the daemon, which routes requsts. Each WebSocket message contains the following fields:

{
    "command": "get_blockchain_state",
    "ack": false,
    "data": {},
    "request_id": "123456",
    "destination": "wallet",
    "origin": "ui",
}

Some examples:

Get blockchain state

# Request

curl --insecure --cert ~/.chia/mainnet/config/ssl/fullnode/private_full_node.crt \
--key ~/.chia/mainnet/config/ssl/fullnode/private_full_node.key \
-d '{"":""}' -H "Content-Type: application/json" -X POST https://localhost:8555/get_blockchain_state

# Response:

{
    "blockchain_state": {
        "difficulty": 7,
        "genesis_challenge_initialized": true,
        "mempool_size": 0,
        "peak": {... },
        "space": 73659118,
        "sub_slot_iters": 134217728,
        "sync": {
            "sync_mode": false,
            "sync_progress_height": 0,
            "sync_tip_height": 0,
            "synced": false
        }
    },
    "success": true
}

Get next address

# Request

curl --insecure --cert ~/.chia/testnet/config/ssl/wallet/private_wallet.crt --key ~/.chia/testnet/config/ssl/wallet/private_wallet.key -d '{"wallet_id": 1, "new_address":true}' -H "Content-Type: application/json" -X POST https://localhost:9256/get_next_address | python -m json.tool

# Response

{
    "address": "xch1d67xq5ed99l4fk2cr33xlq7sj705amnjz9ymc68kw68x3m9qa69sk3ngur",
    "success": true,
    "wallet_id": 1
}

Get Wallet Balance

# Request

curl --insecure --cert ~/.chia/testnet/config/ssl/wallet/private_wallet.crt --key ~/.chia/testnet/config/ssl/wallet/private_wallet.key -d '{"wallet_id": 1}' -H "Content-Type: application/json" -X POST https://localhost:9256/get_wallet_balance | python -m json.tool

# Response
{
    "success": true,
    "wallet_balance": {
        "confirmed_wallet_balance": 0,
        "max_send_amount": 0,
        "pending_change": 0,
        "spendable_balance": 0,
        "unconfirmed_wallet_balance": 0,
        "wallet_id": 1
    }
}
(v

Full Api Reference

Full Node

get_blockchain_state

Returns current information about the blockchain, including the peak, sync information, difficulty, mempool size, etc. Response

{"blockchain_state": {...}}

get_block

Gets a full block by header hash. Params

header_hash: the header hash of the block to get

Response

{"block": {...}}

get_blocks

Gets a list of full blocks. Params

start: the start height
end: the end height (non-inclusive)
exclude_header_hash: whether to exclude the header hash in the response (default false)

Response

{"blocks": [...]}

get_block_record_by_height

Retrieves a block record by height (assuming the height <= peak height). Params

height: the height to get

Response

{"block_record": [...]}

get_block_record

Retrieves a block record by header hash. Params

header_hash: the block's header_hash

Response

{"block_record": [...]}

get_block_records

Retrieves block records in a range. Params

start: the start height
end: the end height (non-inclusive)

Response

{"block_records": [...]}

get_unfinished_block_headers

Retrieves recent unfinished header blocks.

Response

{"headers": [...]}

get_network_space

Retrieves an estimate of the total plotted space of all farmers, in bytes.

Params

older_block_header_hash: the start header hash
newer_block_headre_hash: the end header hash

Response

{"space": 100000000000000000}

get_additions_and_removals

Retrieves the additions and removals (state transitions) for a certain block. Returns coin records for each addition and removal.

Params

header_hash: header hash of the block
newer_block_headre_hash: the end header hash

Response

{"additions": [...], "removals": [...]}

get_initial_freeze_period

Retrieves the initial freeze period for the blockchain (no transactions allowed).

Response

{"INITIAL_FREEZE_PERIOD": 193536}

get_network_info

Retrieves some information about the current network.

Response

{"network_name": "mainnet", "network_prefix":  "xch"}

get_coin_records_by_puzzle_hash

Retrieves a list of coin records with a certain puzzle hash.

Params

puzzle_hash: puzzle hash to search for
start_height (optional): confirmation start height for search
end_height (optional): confirmation end height for search
include_spend_coins: whether to include spent coins too, instead of just unspent

Response

{"coin_records": [...]}

get_coin_record_by_name

Retrieves a coin record by its name/id.

Params

name: coin name

Response

{"coin_record": {...}}

push_tx

Pushes a transaction / spend bundle to the mempool and blockchain. Returns whether the spend bundle was successfully included into the mempool.

Params

spend_bundle: spend bundle to submit, in JSON

Response

{"status": "SUCCESS"}

get_all_mempool_tx_ids

Returns a list of all transaction IDs (spend bundle hashes) in the mempool.

Response

{"tx_ids":  [...]}

get_all_mempool_items

Returns all items in the mempool.

Response

{"mempool_items":  [...]}

get_mempool_item_by_tx_id

Gets a mempool item by tx id.

Params

tx_id: spend bundle hash

Response

{"mempool_item": {...}}

Wallet

log_in

get_public_keys

get_private_key

generate_mnemonic

add_key

delete_key

delete_all_keys

get_sync_status

get_height_info

farm_block

get_initial_freeze_period

get_network_info

get_wallets

create_new_wallet

get_wallet_balance

get_transaction

get_transactions

get_next_address

send_transaction

create_backup

get_transaction_count

get_farmed_amount

Harvester

get_plots

Gets a list of plots being farmed on this harvester.

Response

{"plots": [...], "failed_to_open_filenames": [...], "not_found_filenames": [...]}

refresh_plots

Refreshes the plots, forces the harvester to search for and load new plots.

delete_plot

Deletes a plot file and removes it from the harvester.

Params

filename: name of the file to delete

add_plot_directory

Adds a plot directory (not including sub-directories) to the harvester and configuration. Plots will be loaded and farmed eventually.

Params

dirname: absolute path of the directory to add

get_plot_directories

Returns all of the plot directoried being farmed.

Response

{"directories": []}

remove_plot_directory

Removes a plot directory from the config, does not actually delete the directory.

Params

dirname: absolute path of the directory to remove

Farmer

get_signage_point

Gets a signage point by signage point hash, as well as any winning proofs.

Params

sp_hash: the hash of the challenge chain signage point

Response

{"signage_point": {...}, "proofs": [...]}

get_signage_points

Gets a list of recent signage points as well as winning proofs.

Response

{"signage_points": [...]}

get_reward_targets

Gets the addresses that the farmer is farming to.

Params

search_for_private_key: whether to check if we own the private key 
for these addreses. Can take a long time{, and not guaranteed to return True.

Response

{
  "farmer_target": "xch1..",
  "pool_target": "xch1..", 
  "have_farmer_sk": true,
  "have_pool_sk":  true
}

set_reward_targets

Sets the reward targets in the farmer and configuration file.

Params

farmer_target: farmer target address
pool_target: pool target address

Shared

get_connections

Returns a list of peers that we are currently connected to.

Response

{"connections": [...]}

open_connection

close_connection

stop_node