> For the complete documentation index, see [llms.txt](https://berinis-organization.gitbook.io/ono/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://berinis-organization.gitbook.io/ono/developers/api-reference.md).

# Core API reference

Every ONO core node exposes the same REST API and WebSocket feed. The public node is at:

```
http://core.ono.gg
```

All responses are JSON. Requests are validated against the node's OpenAPI spec — a request that doesn't match the schema is rejected before it reaches any handler.

Field formats used throughout:

* **address** — 66 hex characters (a compressed public key)
* **hash** — 64 hex characters
* **signature** — 128 hex characters
* **timestamp** — Unix seconds

## Balances

### `GET /balance/{address}`

Returns the address's balance record:

```json
{
    "address": "03f6a0…",
    "balance": 1250.5,        // spendable coins
    "burned": 100,             // total sent to the burn address (forging weight)
    "affectedBlockId": 20154,  // last block that touched this balance
    "createdAt": "…",
    "updatedAt": "…"
}
```

## Transactions

### `POST /transaction/init`

Submit a signed transaction to the network. Body:

```json
{
    "from": "03f6a0…",
    "to": "02d4c1…",
    "amount": 1.5,
    "fee": 0.00015,
    "timestamp": 1786019896,
    "hash": "7206734a…",
    "signature": "feee20f1…"
}
```

All fields are required. The node verifies the hash, the signature, the fee (must equal 0.01% of the amount, capped at 0.01), and the sender's balance; a valid transaction enters the pool and is broadcast to peers. The easiest way to build a valid body is [`ono-web`](/ono/developers/quickstart.md)'s `generateTransaction`.

The hash is a SHA-256 over the domain-separated preimage `transaction|<network>|amount=…|from=…|timestamp=…|to=…` (fields sorted alphabetically, `%`, `|`, `=` percent-escaped in values; network is `mainnet` or `testnet`). The signature is canonical (low-S) secp256k1 ECDSA over the hash.

### `GET /transaction/by-hash/{hash}`

Returns the transaction, including its block reference once it has been mined.

### `GET /transaction/by-address/{address}`

Returns the address's transactions (sent and received). The total count is returned in the `X-Total-Count` response header.

Query parameters:

| Parameter   | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `limit`     | Max results, 0–30 (default 30)                             |
| `skip`      | Offset for pagination                                      |
| `order`     | `ASC` or `DESC` (default `DESC`)                           |
| `direction` | Filter to `to` (received) or `from` (sent) only            |
| `maxId`     | Only transactions with id ≤ this value (stable pagination) |
| `hash`      | Filter by exact transaction hash                           |

### `GET /transaction/count-by-address/{address}`

Returns the total number of transactions involving the address.

## Blocks

### `GET /block/{id}`

Returns the block with the given height (the genesis block is id `0`), including its transactions.

### `GET /block/chain?fromId=&limit=`

Returns up to `limit` (max 30) consecutive blocks starting from `fromId`. This is the same endpoint nodes use to sync from each other.

## Peers

### `POST /peer`

Announce a node address to this node. Body:

```json
{ "address": "http://my-node.example.com:4000" }
```

## WebSocket feed

Connect a WebSocket to `wss://core.ono.gg/ws`. The node pushes JSON messages of the form `{ "type": "…", "data": … }`:

| Type              | Data                                                                    |
| ----------------- | ----------------------------------------------------------------------- |
| `NEW_TRANSACTION` | A transaction entering the mempool                                      |
| `NEW_BLOCK`       | A freshly forged block                                                  |
| `STATUS`          | `{ lastBlockId, lastBlockHash }` — sent on connect and every 30 seconds |

Other message types belong to the node-to-node protocol and can be ignored. The [`ono-web`](/ono/developers/quickstart.md) clients wrap this feed with automatic keep-alive.

## Operator endpoints

Routes under `/secure/*` (node stats, chain rollback) are for node operators only. They are disabled unless the node runs with `ALLOW_SECURE_ROUTES=true` and require the operator's authorization header — see [Run a node](/ono/developers/run-a-node.md).