API overview & authentication

The Hub’s public API is served at https://testnet-rpc.necter.network. The endpoint reference is generated from its OpenAPI specification and lists every public /v1 operation with its parameters, request bodies and responses.

curl -s https://testnet-rpc.necter.network/             # network descriptor: contracts, hosts, versions
curl -s https://testnet-rpc.necter.network/v1/status    # validators, indexer, relay connections

Conventions

• Every response is application/json; charset=utf-8, including errors and unknown paths (JSON 404). The only binary responses are GET /v1/modules/{address}/hbc and GET /v1/assets/{sha256}.
• Field names are snake_case. Timestamps are unix seconds and end in _at. Token amounts are decimal strings in base units (wei); token objects carry decimals. Hashes, ids and addresses are lowercase 0x hex.
• No cookies, no redirects, no HTML.

Authentication

Scheme	How	Used for
none		public reads, /v1/execute (rate-limited per IP), claims lookup by address
session	Authorization: Bearer <token> from Sign-In with Ethereum (POST /v1/auth/nonce → sign → POST /v1/auth/siwe), 12 hours	everything under /v1/me, subscriptions, developer actions
apiKey	Authorization: Bearer nk_test_<id>_<secret>, scoped (tasks:submit, projects:read, projects:write, modules:write, analytics:read)	backends: tasks, uploads, analytics
nodeSig	signed X-Ndsr-* headers from a node key	miners and validators

Walkthrough with code: Sign in and enroll.

Pagination

Lists take ?limit=1..200 (default 50) and ?cursor=<opaque> and answer {"items": [...], "next_cursor": "…" | null}.

Errors

{"error": "invalid_field", "message": "wait must be 0..120", "details": {}, "request_id": "65416d30a053d774"}

error codes are stable; message is for humans; include request_id when you report a problem. The codes you will meet most: Troubleshooting.

Rate limits

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds); a 429 adds Retry-After. Budgets are per API key, per session wallet, per node key, and per IP for anonymous calls (for example 60 /v1/execute calls per minute per IP).

CORS

Anonymous GET endpoints answer Access-Control-Allow-Origin: *, so web pages can read projects, modules, explorer data and network status directly. Authenticated endpoints and POST /v1/execute accept only the Necter apps’ origins, so third-party web apps call them through their own backend.

Other surfaces

• Miner relay: wss://testnet-rpc.necter.network/v1/relay, WebSocket subprotocol necter-relay.v1. It is used by the miner apps; its protocol (handshake, offers, leases, votes, acks, resume) is part of the miner.
• Node routes (/v1/nodes/* and the legacy /api/* node paths) are for validators and are not listed in the reference.