Blockfrost Compatibility

Nexus serves a Blockfrost-compatible surface at https://nexus.gerowallet.io/api/v0. Point an unmodified Blockfrost SDK at that base URL and pass your Nexus nxs_ key as the project_id, and your existing calls keep working against Blockfrost’s request and response shapes.

This page is for developers arriving from Blockfrost. If you already call the native Nexus API at /api/... with an X-Api-Key header, nothing here changes for you and there is nothing to do. The compatible surface is an additional entry point, not a replacement.

The one-line change

Two changed lines in @blockfrost/blockfrost-js: your project ID becomes your Nexus key, and customBackend points at /api/v0.

 const api = new BlockFrostAPI({
-  projectId: "mainnetYourProjectId",
+  projectId: "nxs_your_nexus_key",
+  customBackend: "https://nexus.gerowallet.io/api/v0",
 });

curl -X GET "https://nexus.gerowallet.io/api/v0/blocks/latest" \
  -H "project_id: nxs_your_api_key_here"

That is the whole migration. Same SDK, same method calls, same response shapes.

project_id is accepted only on /api/v0, and it carries the same nxs_ key you would use natively. X-Api-Key also works on this surface, and an explicit X-Api-Key wins if a request sends both. See Authentication.

What works

Most of the Blockfrost read surface is served today:

Blocks and transactions
Addresses
Accounts, through the stake-address sub-resources
Assets, by asset ID and by policy ID
Epochs
Scripts
Transaction metadata
Stake pools: the pool list, /pools/retired, /pools/retiring, and the per-pool sub-resources metadata, relays, updates, blocks and votes

The exceptions inside those areas are listed below, in full.

What is not available yet

Guarded endpoints

These paths return a Blockfrost-shaped 503 with a Retry-After header. The cause is unbounded per-request aggregation in the upstream indexer, so each path is guarded individually and is released on its own as the matching upstream fix lands.

Blockfrost path	Note
`/pools/{pool_id}`	Pool detail
`/pools/{pool_id}/history`	Per-epoch pool history
`/pools/{pool_id}/delegators`	Pool delegator list
`/pools/extended`	Pool list with per-pool enrichment
`/assets`	The unfiltered asset list. `/assets/{asset}` and `/assets/policy/{policy_id}` are served
`/epochs/{number}/previous`	Preceding-epoch listing

Tracked upstream in bloxbean/yaci-store: #1078, #1080, #1083, #1089.

Not supported by design

Mempool endpoints.
Blockfrost’s account-usage metrics endpoints.

These are Blockfrost product surface rather than chain data, and Nexus does not serve them.

/accounts/{stake_address}, the account root, is also not served yet. That one is an upstream gap rather than a Nexus decision, tracked in bloxbean/yaci-store#1077. The sub-resources under a stake address are served.

Error responses

On /api/v0, Nexus returns Blockfrost’s error envelopes rather than the native Nexus error body, so an unmodified SDK parses them without changes. Every envelope is UTF-8. A key that is present but refused returns 403:

{
  "status_code": 403,
  "error": "Forbidden",
  "message": "Invalid project token."
}

A request with no key at all returns 403 with a different message, because a missing header and a wrong key need different fixes:

{
  "status_code": 403,
  "error": "Forbidden",
  "message": "Missing project token. Please include project_id in your request."
}

The rest:

Condition	Status	Envelope
Over limit	429	Blockfrost’s `Project Over Limit`, with a `Retry-After` header
Guarded or unavailable path	503	Blockfrost-shaped, with a `Retry-After` header

These shapes apply to /api/v0 only. The native /api/... surface returns the Nexus error envelope, with timestamp, status, error, message, path and requestId. See Error Handling.

Rate limits and quota

One key, one tier, one set of limits. Your nxs_ key carries the same plan tier on both surfaces, and traffic through /api/v0 counts against the same monthly quota and the same per-second rate limit as native traffic. There is no separate compatibility allowance and no second key to manage. The per-tier numbers are on Rate Limits. A 429 on /api/v0 uses the Blockfrost envelope described above and still sends Retry-After, so an SDK’s built-in backoff behaves the way it does against hosted Blockfrost.

Guarded 503 responses currently consume quota. That is the behaviour today, and it is under review.

Moving individual calls to the native API

Optional, and only where it pays. Once you are running on Nexus, individual calls can move to the native API, which has endpoints that answer in one request what the Blockfrost surface needs many requests to assemble. A wallet page is the clearest case. Built through the Blockfrost SDK it takes 42 calls; the native GET /api/addresses/{address}/transactions/history answers the same page in 1. This is a quota and code-structure argument, not a latency one. What changes is that the page spends 1 request of your monthly quota instead of 42, and you maintain a single call instead of a fan-out.

Nothing forces this. A working Blockfrost integration on /api/v0 can stay exactly as it is.

Stability

The base URL and your key are the contract. https://nexus.gerowallet.io/api/v0 plus your nxs_ key is what you integrate against, and that pair does not change. What answers behind that URL is ours to improve. Backend changes never require action on your side: no new URL, no key rotation, no forced SDK upgrade.

Next steps

Authentication

project_id, X-Api-Key, and how keys are scoped

Rate Limits

Per-tier quotas and per-second limits

Error Handling

The native error envelope and how to branch on it

API Reference

The native Nexus surface, endpoint by endpoint

Getting Started

Core Concepts

Add-ons & Streaming

API Reference

The one-line change

What works

What is not available yet

Guarded endpoints

Not supported by design

Error responses

Rate limits and quota

Moving individual calls to the native API

Stability

Next steps

Authentication

Rate Limits

Error Handling

API Reference

​The one-line change

​What works

​What is not available yet

​Guarded endpoints

​Not supported by design

​Error responses

​Rate limits and quota

​Moving individual calls to the native API

​Stability

​Next steps

Authentication

Rate Limits

Error Handling

API Reference

The one-line change

What works

What is not available yet

Guarded endpoints

Not supported by design

Error responses

Rate limits and quota

Moving individual calls to the native API

Stability

Next steps