JSON-RPC API Reference

The ACDC JSON-RPC API provides programmatic access to both Alpha and Delta chains. All methods follow the JSON-RPC 2.0 specification.

Request Format

curl -X POST <endpoint> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "<method_name>",
    "params": [<parameters>]
  }'

Chain Methods

chain_getInfo

Returns general information about the chain.

Parameters: None

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "chain_getInfo",
  "params": []
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "chain": "alpha",
    "version": "1.0.0",
    "blockHeight": 1234567,
    "networkId": "mainnet",
    "peerCount": 42
  }
}

chain_getBlockByNumber

Retrieves a block by its height.

Parameters:

Name	Type	Required	Description
blockNumber	integer	Yes	Block height
fullTx	boolean	No	Include full transactions (default: false)

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "chain_getBlockByNumber",
  "params": [1234567, true]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "number": 1234567,
    "hash": "0xabc123...",
    "parentHash": "0xdef456...",
    "timestamp": 1704067200,
    "transactions": ["0xtx1...", "0xtx2..."],
    "stateRoot": "0xstate...",
    "receiptsRoot": "0xreceipts..."
  }
}

chain_getBlockByHash

Retrieves a block by its hash.

Parameters:

Name	Type	Required	Description
blockHash	string	Yes	Block hash (hex)
fullTx	boolean	No	Include full transactions (default: false)

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "chain_getBlockByHash",
  "params": ["0xabc123...", false]
}

Account Methods

account_getBalance

Returns the balance of an account.

Parameters:

Name	Type	Required	Description
address	string	Yes	Account address (ax1... or dx1...)
blockNumber	integer/string	No	Block height or "latest" (default: "latest")

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "account_getBalance",
  "params": ["dx1abc123xyz...", "latest"]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "balance": "1000000000000000000",
    "nonce": 42,
    "blockNumber": 1234567
  }
}

account_getNonce

Returns the current nonce for an account.

Parameters:

Name	Type	Required	Description
address	string	Yes	Account address

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "account_getNonce",
  "params": ["dx1abc123xyz..."]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "nonce": 42
  }
}

Transaction Methods

tx_sendRawTransaction

Submits a signed transaction to the network.

Parameters:

Name	Type	Required	Description
signedTx	string	Yes	Signed transaction (hex encoded)

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tx_sendRawTransaction",
  "params": ["0xf86c808504a817c80082520894..."]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txHash": "0xabc123...",
    "status": "pending"
  }
}

tx_getTransaction

Retrieves transaction details by hash.

Parameters:

Name	Type	Required	Description
txHash	string	Yes	Transaction hash

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tx_getTransaction",
  "params": ["0xabc123..."]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hash": "0xabc123...",
    "from": "dx1sender...",
    "to": "dx1receiver...",
    "value": "1000000000000000000",
    "nonce": 42,
    "blockNumber": 1234567,
    "blockHash": "0xblock...",
    "transactionIndex": 0,
    "status": "confirmed"
  }
}

tx_getTransactionReceipt

Retrieves the receipt of a confirmed transaction.

Parameters:

Name	Type	Required	Description
txHash	string	Yes	Transaction hash

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tx_getTransactionReceipt",
  "params": ["0xabc123..."]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transactionHash": "0xabc123...",
    "blockNumber": 1234567,
    "blockHash": "0xblock...",
    "status": 1,
    "gasUsed": "21000",
    "logs": []
  }
}

Alpha Chain Specific Methods

alpha_getRecord

Retrieves a record (UTXO) by its commitment.

Parameters:

Name	Type	Required	Description
commitment	string	Yes	Record commitment hash

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "alpha_getRecord",
  "params": ["0xcommitment..."]
}

alpha_getSerialNumber

Checks if a serial number has been spent.

Parameters:

Name	Type	Required	Description
serialNumber	string	Yes	Serial number to check

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "alpha_getSerialNumber",
  "params": ["0xserial..."]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "spent": true,
    "blockNumber": 1234567
  }
}

Delta Chain Specific Methods

delta_getStake

Returns staking information for an address.

Parameters:

Name	Type	Required	Description
address	string	Yes	Staker address

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "delta_getStake",
  "params": ["dx1staker..."]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "stakedAmount": "10000000000000000000000",
    "delegatedTo": "dx1validator...",
    "rewards": "500000000000000000",
    "unbondingAmount": "0",
    "unbondingCompleteTime": null
  }
}

delta_getValidator

Returns validator information.

Parameters:

Name	Type	Required	Description
address	string	Yes	Validator address

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "delta_getValidator",
  "params": ["dx1validator..."]
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "dx1validator...",
    "stake": "1000000000000000000000000",
    "delegatedStake": "5000000000000000000000000",
    "commission": 0.05,
    "status": "active",
    "uptime": 0.9995
  }
}

Error Codes

Code	Message	Description
-32700	Parse error	Invalid JSON
-32600	Invalid request	Missing required fields
-32601	Method not found	Unknown method name
-32602	Invalid params	Invalid parameter type or value
-32603	Internal error	Server-side error
-32000	Transaction rejected	Invalid transaction
-32001	Insufficient funds	Account balance too low
-32002	Nonce too low	Transaction nonce already used
-32003	Nonce too high	Gap in transaction nonce