# Armchain API

Beyond the standard Ethereum JSON-RPC methods, Armchain provides additional API namespaces for querying DAG data, epoch information, and validator state. These are useful when you need to interact with Armchain's consensus layer directly.

## arm Namespace

The `arm` namespace provides Armchain-specific methods. These are available when `arm` is enabled in `--http.api`.

### arm\_getBalance

Returns the balance at a given address (alias for `eth_getBalance`).

```bash
curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"arm_getBalance","params":["0xADDRESS","latest"],"id":1}'
```

### arm\_getTransactionCount

Returns the transaction count (nonce) for an address.

```bash
curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"arm_getTransactionCount","params":["0xADDRESS","latest"],"id":1}'
```

### arm\_sendTransaction

Send a transaction (account must be unlocked on the node).

```bash
curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"arm_sendTransaction",
    "params":[{
      "from": "0xFROM",
      "to": "0xTO",
      "value": "0xDE0B6B3A7640000"
    }],
    "id":1
  }'
```

***

## dag Namespace

The `dag` namespace provides access to the DAG (Directed Acyclic Graph) data structures that underpin Lachesis consensus.

### dag\_getEvent

Returns a DAG event by its hash.

**Parameters:**

1. `eventHash`: 32-byte event hash

```bash
curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"dag_getEvent","params":["0xEVENT_HASH"],"id":1}'
```

**Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hash": "0x...",
    "creator": 1,
    "epoch": 42,
    "seq": 1057,
    "frame": 100,
    "isRoot": false,
    "parents": ["0xPARENT_1", "0xPARENT_2"],
    "gasPowerLeft": { "shortTerm": 1000000, "longTerm": 5000000 },
    "gasPowerUsed": 28000,
    "txHash": "0x...",
    "lamportTime": 50000,
    "creationTime": 1708300000000000000
  }
}
```

### dag\_getEventsByEpoch

Returns events in a specific epoch.

**Parameters:**

1. `epoch`: Epoch number

```bash
curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"dag_getEventsByEpoch","params":["0x2A"],"id":1}'
```

### dag\_getEpochStats

Returns statistics for the current or specified epoch.

**Parameters:**

1. `epoch`: (optional) Epoch number. Defaults to current epoch.

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

### dag\_getHeads

Returns the current head events in the DAG (latest events from each validator).

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

***

## aBFT Information

### abft\_getValidators

Returns the current validator set.

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

**Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "epoch": 42,
    "validators": [
      {
        "id": 1,
        "pubkey": "0x01...",
        "stake": "1000000000000000000000000",
        "address": "0x..."
      }
    ]
  }
}
```

### abft\_getDowntime

Returns downtime information for a validator.

**Parameters:**

1. `validatorId`: Validator ID

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

### abft\_getEpoch

Returns the current epoch number.

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

***

## debug Namespace

### debug\_traceTransaction

Replays a transaction and returns execution traces.

**Parameters:**

1. `txHash`: Transaction hash
2. `options`: (optional) Tracing options

```bash
curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"debug_traceTransaction",
    "params":["0xTX_HASH", {"tracer": "callTracer"}],
    "id":1
  }'
```

### debug\_traceCall

Traces a call without executing it on-chain.

```bash
curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"debug_traceCall",
    "params":[{
      "from": "0xFROM",
      "to": "0xTO",
      "data": "0xCALLDATA"
    }, "latest", {"tracer": "callTracer"}],
    "id":1
  }'
```

***

## Transaction Object Fields (Type 3)

When querying Type 3 PQC transactions, the response includes these fields:

| Field                  | Type     | Description                                         |
| ---------------------- | -------- | --------------------------------------------------- |
| `type`                 | `string` | `"0x3"` - PQC transaction type                      |
| `hash`                 | `string` | Transaction hash                                    |
| `from`                 | `string` | Sender address (derived from ML-DSA44 public key)   |
| `to`                   | `string` | Recipient address (or `null` for contract creation) |
| `value`                | `string` | Transfer value in wei                               |
| `nonce`                | `string` | Sender nonce                                        |
| `gas` / `gasLimit`     | `string` | Gas limit                                           |
| `maxFeePerGas`         | `string` | Maximum total fee per gas                           |
| `maxPriorityFeePerGas` | `string` | Priority fee per gas                                |
| `input` / `data`       | `string` | Transaction input data                              |
| `chainId`              | `string` | Chain ID                                            |
| `blockNumber`          | `string` | Block number (when mined)                           |
| `blockHash`            | `string` | Block hash (when mined)                             |
| `transactionIndex`     | `string` | Index in block                                      |

> **Note**: Type 3 transactions do not have `v`, `r`, `s` fields. Signature data is in the `signatureBlob` field.

***

## Enabling API Namespaces

```bash
# Enable specific namespaces
./build/armnode \
  --http \
  --http.api eth,net,web3,arm,dag,txpool,debug,admin,personal \
  --ws \
  --ws.api eth,net,web3,arm,dag
```

> **Security**: Only enable `personal`, `admin`, and `debug` on trusted/local networks.

## Further Reading

* [JSON-RPC Standard Methods](/api-reference/json-rpc.md): Standard Ethereum RPC methods
* [DAG Structure](/architecture/dag.md): Understanding DAG events
* [Consensus](/architecture/consensus.md): Lachesis aBFT and epochs
* [Fakenet](/node-operators/fakenet.md): Local development network setup


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.armchain.org/api-reference/armchain-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.