> ## Documentation Index
> Fetch the complete documentation index at: https://nexus.gerowallet.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Blockfrost Compatibility

> Point an unmodified Blockfrost SDK at Nexus by changing one line

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.

<Note>
  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.
</Note>

## The one-line change

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

<CodeGroup>
  ```diff blockfrost-js theme={null}
   const api = new BlockFrostAPI({
  -  projectId: "mainnetYourProjectId",
  +  projectId: "nxs_your_nexus_key",
  +  customBackend: "https://nexus.gerowallet.io/api/v0",
   });
  ```

  ```bash cURL theme={null}
  curl -X GET "https://nexus.gerowallet.io/api/v0/blocks/latest" \
    -H "project_id: nxs_your_api_key_here"
  ```
</CodeGroup>

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

<Note>
  `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](/docs/authentication#blockfrost-sdks-and-the-project-id-header).
</Note>

## 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](https://github.com/bloxbean/yaci-store/issues/1078),
[#1080](https://github.com/bloxbean/yaci-store/issues/1080),
[#1083](https://github.com/bloxbean/yaci-store/issues/1083),
[#1089](https://github.com/bloxbean/yaci-store/issues/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.

<Note>
  `/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](https://github.com/bloxbean/yaci-store/issues/1077). The
  sub-resources under a stake address are served.
</Note>

## 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**:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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                 |

<Warning>
  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](/docs/concepts/error-handling).
</Warning>

## 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](/docs/concepts/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.

<Note>
  Guarded **503** responses currently consume quota. That is the behaviour today, and it is under
  review.
</Note>

## 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.

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

## 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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/authentication">
    `project_id`, `X-Api-Key`, and how keys are scoped
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/docs/concepts/rate-limits">
    Per-tier quotas and per-second limits
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/docs/concepts/error-handling">
    The native error envelope and how to branch on it
  </Card>

  <Card title="API Reference" icon="book" href="/docs/api-reference">
    The native Nexus surface, endpoint by endpoint
  </Card>
</CardGroup>