RPC API Reference

The Arch Network provides a comprehensive JSON-RPC API for interacting with validator nodes. This API allows you to:

• Query account information and balances
• Submit transactions to the network
• Retrieve block and transaction data
• Monitor network state and readiness
• Manage validator operations

::::note RPC Method Availability: For a complete list of which RPC methods are available in the validator vs local_validator crates, along with their correct parameter formats, see the RPC section below. ::::

API Endpoints

Default Configuration

• Default Port: 9001 for validator nodes, 9002 for local validators
• Endpoint URL: http://localhost:9002 (or your node's IP address)
• Protocol: HTTP POST with JSON-RPC 2.0

Request Format

All RPC requests must be sent as HTTP POST requests with:

• Content-Type: application/json
• JSON-RPC Version: "2.0"

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "method_name",
  "params": [/* parameters */]
}

Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {/* response data */}
}

Available Methods

Account Operations

• read_account_info - Get account information
• get_account_address - Get Bitcoin address for account
• get_program_accounts - Query accounts by program ID
• get_all_accounts - Get all account public keys
• get_multiple_accounts - Get multiple accounts in one call

Transaction Operations

• send_transaction - Submit a single transaction
• send_transactions - Submit multiple transactions
• get_processed_transaction - Get transaction status and details
• get_transaction_report - Get detailed transaction processing report
• request_airdrop - Request faucet airdrop to an address
• create_account_with_faucet - Build a faucet-funded create account tx
• recent_transactions - List recent transactions
• get_transactions_by_block - List transactions for a block
• get_transactions_by_ids - Fetch transactions by ids

Block Operations

• get_block - Get block by hash
• get_block_count - Get current block count
• get_block_hash - Get block hash by height
• get_best_block_hash - Get latest block hash
• get_best_finalized_block_hash - Get latest finalized block hash
• get_block_by_height - Get block by height

Network Operations

• is_node_ready - Check node readiness
• get_network_pubkey - Get the network verifying key
• check_pre_anchor_conflict - Check for pre-anchor conflicts

System Operations

• get_version - Get node version information

Account Operations

read_account_info

Retrieves information for a specified account.

Parameters:

1. pubkey - Account public key as a 32-byte array

Returns: Account information object with data, owner, utxo, is_executable, and tag fields.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "read_account_info",
    "params": ["11111111111111111111111111111112"]
  }'

get_account_address

Gets the Bitcoin address associated with an account.

Parameters:

1. pubkey - Account public key as a 32-byte array

Returns: Bitcoin address string.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_account_address",
    "params": ["11111111111111111111111111111112"]
  }'

get_program_accounts

Retrieves all accounts owned by a specific program.

Parameters:

1. program_id - Program public key as a 32-byte array

Returns: Array of account information objects.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_program_accounts",
    "params": ["AplToken111111111111111111111111"]
  }'

get_multiple_accounts

Retrieves info for multiple accounts in one call.

Parameters:

1. pubkeys - Array of account public keys (string-serialized)

Returns: Array of account information objects.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_multiple_accounts",
    "params": [["<pubkey1>", "<pubkey2>"]]
  }'

get_all_accounts

Lists all known account public keys.

Parameters: None

Returns: Array of public keys (hex strings).

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_all_accounts",
    "params": []
  }'

Transaction Operations

send_transaction

Submits a transaction to the network for processing.

Parameters:

1. transaction - Base64-encoded transaction data

Returns: Transaction signature string.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "send_transaction",
    "params": ["base64_encoded_transaction_data"]
  }'

send_transactions

Submits multiple transactions to the network for processing in a single request.

Parameters:

1. transactions - Array of base64-encoded transaction data

Returns: Array of transaction signature strings.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "send_transactions",
    "params": [["base64_tx_1","base64_tx_2"]]
  }'

get_processed_transaction

Retrieves the status and details of a processed transaction.

Parameters:

1. signature - Transaction signature string

Returns: Transaction status and details object.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_processed_transaction",
    "params": ["transaction_signature_here"]
  }'

get_transaction_report

Retrieves a detailed processing report for a transaction.

Parameters:

1. txid - Transaction id (hash) string

Returns: Stringified report details.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_transaction_report",
    "params": ["<txid>"]
  }'

get_arch_txid_from_btc_txid

Looks up the Arch transaction id corresponding to a given Bitcoin txid.

Parameters:

1. btc_txid - Bitcoin transaction id (string)

Returns: Arch txid string or null if not found.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_arch_txid_from_btc_txid",
    "params": ["<btc_txid>"]
  }'

get_latest_tx_using_account

Retrieves the most recent Arch txid that touched the specified account.

Parameters:

1. account_pubkey - Account public key (hex string)

Returns: Arch txid string or null if none found.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_latest_tx_using_account",
    "params": ["<account_pubkey>"]
  }'

request_airdrop

Requests 1_000_000_000 lamports from the local faucet to the specified account.

Parameters:

1. pubkey - Recipient account public key (string-serialized)

Returns: Transaction signature string.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "request_airdrop",
    "params": ["<recipient_pubkey>"]
  }'

create_account_with_faucet

Builds a signed RuntimeTransaction from the faucet to create a new account for the provided public key.

Note: This returns a transaction object; submit it using send_transaction.

Parameters:

1. pubkey - New account public key (string-serialized)

Returns: A transaction object with version, signatures, and message fields.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "create_account_with_faucet",
    "params": ["<new_account_pubkey>"]
  }'

recent_transactions

Retrieves most recent transactions with optional pagination and account filter.

Parameters (object):

• limit (optional, number)
• offset (optional, number)
• account (optional, string-serialized pubkey)

Returns: Array of processed transactions.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "recent_transactions",
    "params": [{"limit": 10}]
  }'

get_transactions_by_block

Lists transactions for a specific block with optional pagination and account filter.

Parameters (object):

• block_hash (string, required)
• limit (optional, number)
• offset (optional, number)
• account (optional, string-serialized pubkey)

Returns: Array of processed transactions.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_transactions_by_block",
    "params": [{"block_hash": "<block_hash>", "limit": 25}]
  }'

get_transactions_by_ids

Fetches transactions by their txids.

Parameters (object):

• txids (array of strings, required)

Returns: Array of processed transactions.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_transactions_by_ids",
    "params": [{"txids": ["<txid1>", "<txid2>"]}]
  }'

Block Operations

get_block

Retrieves block information by block hash.

Parameters:

1. block_hash - Block hash as a 32-byte array

Returns: Block information object.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_block",
    "params": ["block_hash_here"]
  }'

get_block_count

Gets the current block count (height) of the blockchain.

Parameters: None

Returns: Block count as a number.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_block_count",
    "params": []
  }'

get_block_hash

Retrieves the block hash for a given block height.

Parameters:

1. block_height - Block height (number)

Returns: Block hash string.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_block_hash",
    "params": [12345]
  }'

get_block_by_height

Retrieves block information by block height.

Parameters:

1. block_height - Block height (number)

Optionally, a second parameter may request the full block object.

Returns: Block information object.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_block_by_height",
    "params": [12345]
  }'

get_best_block_hash

Gets the latest (tip) block hash.

Parameters: None

Returns: Block hash string.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_best_block_hash",
    "params": []
  }'

get_best_finalized_block_hash

Gets the latest finalized block hash.

Parameters: None

Returns: Block hash string.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_best_finalized_block_hash",
    "params": []
  }'

Network Operations

is_node_ready

Checks if the node is ready to process requests.

Parameters: None

Returns: Boolean indicating node readiness.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "is_node_ready",
    "params": []
  }'

get_peers

Retrieves information about connected network peers.

Parameters: None

Returns: Array of peer information objects.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_peers",
    "params": []
  }'

get_network_pubkey

Returns the validator's network verifying key (group x-pubkey).

Parameters: None

Returns: Hex-encoded x-only public key string.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_network_pubkey",
    "params": []
  }'

check_pre_anchor_conflict

Checks for pre-anchor conflicts for a set of accounts.

Parameters:

1. accounts - Array of account public keys (string-serialized)

Returns: Boolean indicating whether a conflict exists.

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "check_pre_anchor_conflict",
    "params": [["<pubkey1>", "<pubkey2>"]]
  }'

System Operations

get_version

Retrieves node version information.

Parameters: None

Returns: Object containing version and feature_set (optional).

Example:

curl -X POST http://localhost:9002 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "get_version",
    "params": []
  }'

Error Handling

Error Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Additional error details"
  }
}

Common Error Codes

• -32600: Invalid Request
• -32601: Method not found
• -32602: Invalid params
• -32603: Internal error
• -32000: Server error (custom)

SDK Integration

TypeScript SDK

import { Connection } from '@saturnbtcio/arch-sdk';

const connection = new Connection('http://localhost:9002');

// Get account info
const accountInfo = await connection.getAccountInfo(publicKey);

// Send transaction
const signature = await connection.sendTransaction(transaction);

Rust SDK

use arch_sdk::{Connection, Pubkey};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let connection = Connection::new("http://localhost:9002");
    
    // Get account info
    let account_info = connection.get_account_info(&public_key).await?;
    
    // Send transaction
    let signature = connection.send_transaction(&transaction).await?;
    
    Ok(())
}

Best Practices

1. Connection Management

• Use connection pooling for high-frequency requests
• Implement proper timeout handling
• Monitor connection health

2. Error Handling

• Always check for RPC errors
• Implement retry logic for transient failures
• Log errors for debugging

3. Performance

• Batch multiple requests when possible
• Use appropriate polling intervals
• Cache frequently accessed data

4. Security

• Use HTTPS in production
• Implement proper authentication
• Validate all input parameters

Next Steps

Resources