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