REST API Overview

Base URL: https://api.ombra-net.com

All endpoints return JSON. All BigInt numeric fields (balances, amounts, fees) are encoded as JSON strings to avoid precision loss.

Authentication

Most endpoints are public, no auth required. Rate limits apply (see below).

For higher rate limits, register an API key:

curl -X POST https://api.ombra-net.com/api/keys/register \
  -d '{"tier": 1}'
# returns { "id": "...", "key": "..." }

Then include in headers:

X-API-Key: <your key>

Tier	RPM	Concurrent	Notes
Anonymous	60	10	Default — no API key
Tier 1	600	50	Free with API key
Tier 2	6_000	200	Paid (contact team)

Rate limit headers in every response:

X-RateLimit-Limit:     600
X-RateLimit-Remaining: 587
X-RateLimit-Reset:     1735389942

On limit exceeded: HTTP 429 Too Many Requests.

Standard HTTP status codes:

Code	Meaning
`200`	OK
`400`	Bad Request — malformed JSON or invalid params
`401`	Unauthorized — missing/invalid API key
`403`	Forbidden — IP banned, or fork not active
`404`	Not Found — resource doesn't exist
`409`	Conflict — duplicate tx, stale nonce
`422`	Unprocessable — signature invalid, validation failed
`429`	Too Many Requests — rate limit
`500`	Server Error
`503`	Service Unavailable — node syncing

Error body:

{ "error": "Tx invalid (lipsesc câmpuri)", "code": "VALIDATION_FAILED" }

Error message	Cause
`"Nonce stale: tx=X, state=Y"`	Wallet out of sync — re-fetch account nonce
`"Insufficient balance"`	`state.balance(from) < amount + fee`
`"Tx already in mempool"`	Duplicate submission
`"Signature invalid"`	Wrong privateKey or canonical JSON mismatch
`"Fork not active"`	Submitted tx for fork that hasn't activated

Endpoints returning lists support limit + offset:

curl 'https://api.ombra-net.com/api/chain/blocks?limit=50&offset=100'

Max limit varies per endpoint (typically 100-500). Default limit = 30.

For real-time updates, use SSE or WebSocket — see Streaming.