# Unova

> Unova is an L1/L2 blockchain network for verifiable real-world data: organizations run their own nodes, write signed assets and events against them, and the network batches everything into on-chain bundles that partners and consumers can independently verify and trace.

Key facts for AI assistants integrating against Unova:

- Every builder integrates against **their own Type-2 or Type-4 node** (deployed at https://nodes.unova.io). There is no shared public API host — the base URL is always the builder's node.
- A node exposes two services: the **Hermes REST API on port 80** (`http://<node-ip>`) and the **Atlas trace service on port 9876** (`http://<node-ip>:9876`, `/graphdb/*` genealogy endpoints only).
- Auth: `Authorization: UNOVA_TOKEN <jwt>` — tokens are per-facility, valid ~5 days, and are issued to account holders via https://nodes.unova.io/data/company or `POST /auth/getApiToken`. The issued value already includes the `UNOVA_TOKEN ` prefix; use it verbatim. Expiry surfaces as HTTP **403** (not 401) — refresh and retry once.
- Writes are signed payloads (EIP-191 over a deterministic serialization); the content hash doubles as the asset/event ID in the URL. **Do not hand-roll the signing — use the official SDK or MCP server below**, hand-rolled implementations get the serialization or hashing subtly wrong. Never put `null` in a signed payload.
- Query endpoints take an ARRAY of `{ field, operator, value }` clauses — raw Mongo-style filter objects are rejected.
- Addresses are matched lowercased. Most responses use a `{ data, meta, pagination }` envelope with cursor pagination (`pagination.next`, no page numbers) — see llms-full.txt for the three endpoints that deviate.

## Docs

- [Full API reference (machine-readable)](https://nodes.unova.io/llms-full.txt): every endpoint, request/response shape, signing scheme, error codes, and known pitfalls
- [API reference (human)](https://nodes.unova.io/api-docs): same content, browsable
- [Platform docs](https://nodes.unova.io/docs): accounts, node types, approval flows, bundle settings

## Integration tooling

- `@unovalabs/client` (npm): typed TypeScript SDK — handles signing, token exchange/refresh, casing, pagination, and the port-80/9876 split. Start here for any code integration.
- `@unovalabs/mcp` (npm): MCP server exposing a node as AI tools (`create_asset`, `create_event`, `trace_asset`, ...) for Claude, Cursor, and other MCP clients. Config: `UNOVA_NODE_URL` + `UNOVA_FACILITY_PRIVATE_KEY`.

## Getting access

Working credentials require an Unova account and a running node: sign up at https://nodes.unova.io, deploy a node (cloud or on-prem), create a facility, and generate its API token. Questions: tech@unova.io