> 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/quickstart.md).

# Quickstart with ono-web

[`ono-web`](https://www.npmjs.com/package/ono-web) is the official JavaScript library for ONO. It creates HD wallets, builds and submits signed transactions, and subscribes to live events from a core node — in both Node.js and the browser.

Requirements: an ono-core node **>= 1.2.5**; on Node.js, version **18+** (the library uses the global `fetch`).

```bash
npm install ono-web
```

## Send your first transaction

```js
const { wallet, transaction } = require('ono-web');

// 1. Create a wallet (or restore one from an existing mnemonic)
const { mnemonic, seed } = await wallet.newWalletData();
const hdWallet = wallet.hdWallet(seed);
const keyPair = wallet.generateKeyPair(hdWallet, 0);

// 2. Build and sign a transaction locally
const tx = transaction.generateTransaction(
    recipientPublicKeyHex, // 'to' address (compressed public key, hex)
    1.5, // amount
    {
        publicKey: keyPair.publicKey.toString('hex'),
        privateKey: keyPair.privateKey.toString('hex'),
    },
);

// 3. Submit it to the core node
const result = await transaction.sendTransaction(tx);

// 4. Look it up later by hash
const confirmed = await transaction.getTransactionByHash(tx.hash);
```

## Wallet functions

Keys are derived with BIP39/BIP32 at `m/44'/2909'/0'/0/<index>`. An ONO address is the account's compressed public key in hex.

| Function                                  | Description                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------- |
| `wallet.newWalletData()`                  | Generates a fresh mnemonic; resolves to `{ mnemonic, seed }` (seed as hex)            |
| `wallet.walletDataFromMnemonic(mnemonic)` | Restores `{ mnemonic, seed }` from an existing BIP39 mnemonic                         |
| `wallet.hdWallet(seed)`                   | Builds an HD wallet (`hdkey` instance) from a hex seed                                |
| `wallet.generateKeyPair(hdWallet, index)` | Derives the key pair at account index `index`; has `publicKey` / `privateKey` buffers |

## Transaction functions

```js
// Optional configuration — defaults shown:
transaction.setCoreHost(new URL('http://core.ono.gg'));
transaction.setNetwork('mainnet'); // or 'testnet'
```

| Function                                               | Description                                                                                                |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `transaction.setCoreHost(url)`                         | `URL` of the core node used by `sendTransaction` / `getTransactionByHash`                                  |
| `transaction.setNetwork(network)`                      | `'mainnet'` (default) or `'testnet'`. Mixed into the transaction hash, so it must match the node's network |
| `transaction.calculateFee(amount)`                     | Fee preview: 0.01% of the amount, capped at 0.01                                                           |
| `transaction.generateTransaction(to, amount, keyPair)` | Builds, hashes, and signs a transaction locally; returns the complete transaction object                   |
| `transaction.sendTransaction(tx)`                      | POSTs the transaction to the node (`/transaction/init`)                                                    |
| `transaction.getTransactionByHash(hash)`               | Fetches a transaction by hash, including its block reference once mined                                    |

## Live events (WebSocket)

Two clients implement the same subscription protocol — `ServerClient` for Node.js and `BrowserClient` for browsers. Both keep the connection alive automatically.

```js
const { ServerClient } = require('ono-web'); // or BrowserClient in the browser

const client = new ServerClient('http://core.ono.gg'); // http(s) is converted to ws(s)

client.subscribe(
    (message) => {
        switch (message.type) {
            case 'NEW_TRANSACTION': // a transaction entering the mempool
            case 'NEW_BLOCK': // a freshly forged block
            case 'STATUS': // { lastBlockId, lastBlockHash }, on connect and every 30s
                console.log(message.type, message.data);
                break;
        }
    },
    (error) => console.error('bad message', error),
);

// later
client.disconnect();
```

Other message types (peer-to-peer housekeeping like `PONG`, `PEERS_REQUEST`, …) can be ignored.

## Compatibility notes

* **ono-web >= 1.1.0 requires ono-core >= 1.2.5.** The transaction hash preimage is domain-separated (`transaction|<network>|amount=…|from=…|timestamp=…|to=…`); older cores reject transactions built by this version and vice versa.
* Signatures are canonical (low-S) ECDSA over secp256k1.
* When talking to a node running with `TESTNET=true`, call `transaction.setNetwork('testnet')` before generating transactions.