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

# Sponsored Accounts

> When another organization pays for your Nexus API usage: what you get, your limits, and the responses to expect

A sponsored account is a Nexus account whose API usage another organization pays for: your sponsor. You keep your own account, your own team and your own API keys, and you need no plan of your own. Your requests are served under your sponsor's plan and counted against your sponsor's monthly request pool. Your sponsor can also set a monthly cap for your account.

> [!NOTE]
>
> Sponsor programs are arranged with the Nexus team, who add, cap and end sponsored accounts at the sponsor's request. To set one up, [contact us](https://nexus.gerowallet.io/support).

Only a personal account can be sponsored, not a team you created. Members of your team are covered too: see [Team members](#team-members).

## How to tell your account is sponsored

The dashboard says so in three places.

| Where | What it shows |
| - | - |
| Plan pill | **Sponsored**, your sponsor's name under it, and a state: **Active**, **Ending** with a date, or **Paused** |
| Billing page | A card titled **Sponsored by** followed by your sponsor's name, saying "pays for this account's usage. You are not charged." |
| Overview, Plan usage card | "This month, paid by" followed by your sponsor's name |

The pill reads **Ending** with the date only in the last 30 days before an end date. Before that it reads **Active**.

The billing page card lists what the sponsorship gives you:

| Row | Meaning |
| - | - |
| Included | The add-ons and WebSocket access your keys get |
| Rate limit | Your per-second rate limit and burst |
| Monthly cap | Your cap and how much of it you used, or **No cap** |
| Shared pool | Your sponsor's pool as **Available**, **Running low** or **Used up** |
| API keys | How many active keys you may have, and how many are in use |
| Sponsored since | When the sponsorship started |
| Ends | The end date, or **No end date** |

When your sponsor gave a contact email, the card has a **Contact** button for it.

### Banners

One banner at a time shows at the top of every dashboard page, in this order of priority:

| Banner title | When |
| - | - |
| Sponsored API access is paused | Your sponsorship is paused. Requests from your keys are rejected. |
| You reached your monthly cap | Your own cap is used up for this month. |
| The shared pool is used up | Your sponsor's pool is used up for this month. |
| Sponsored access may pause on (a date) | Access may pause on that date. |
| Sponsored access ends on (a date) | The sponsorship ends on that date. Shown in the last 30 days before it. |
| The shared pool is running low | 80 percent or more of your sponsor's pool is used. |

## What is included

* **API keys.** Create keys as usual from the dashboard. Your account needs no plan of its own. The number of active keys is set by your sponsorship, not by your sponsor's plan; the billing page shows it under API keys.
* **Add-ons.** Of Market Data, Wallet Analytics, Transaction Builder, MCP Server and IPFS, your keys get whichever your sponsor's plan includes; the billing page lists them under Included. An add-on setting on a single key can only turn an add-on off for that key. It cannot add one your sponsor's plan does not include.
* **Rate limit.** Your per-second rate limit and burst are set for your account by your sponsorship, and never above your sponsor's plan. Your account has its own bucket: other accounts your sponsor pays for do not use it up.
* **WebSocket.** Market-data streaming comes from your sponsor too. See [WebSocket](#websocket).

## The two monthly limits

A sponsored request is checked against two monthly limits, in this order.

### Your own cap

Your sponsor can set a monthly cap for your account. When it is set, you see it in full: the cap, and how many requests your keys made this month. The billing page shows both, and the Overview's **Your requests** meter counts against it. Without a cap, the Overview shows your requests with **No cap**.

When the cap is reached, your requests get a 429 with `"scope": "sponsored_cap"` (see [Responses](#responses)).

### Your sponsor's shared pool

Your requests also count against your sponsor's monthly request pool, which your sponsor shares with every account it pays for. You never see a number for the pool: not its size, not its use. You see only its state, on the billing page and the Plan usage card:

| State | Meaning |
| - | - |
| Available | Less than 80 percent of the pool is used |
| Running low | 80 percent or more is used |
| Used up | The pool is used up. Requests get a 429 with `"scope": "sponsor_pool"` |

While the sponsorship is paused, no pool state is shown.

### When they reset

Both limits reset at **00:00 UTC on the 1st** of each month, with every other monthly counter. Your requests can still be refused for up to about a minute after that instant, while every server picks up the reset.

> [!NOTE]
>
> The cap and the pool are counted in batches across Nexus's servers, so they are limits, not reservations. A few seconds of requests past a limit can still be served before the 429s start.

## Responses

The bodies below are those of the native surface (`/api/...`). On the [Blockfrost-compatible surface](https://nexus.gerowallet.io/docs/blockfrost-compatibility.md) (`/api/v0`), the same refusals use Blockfrost's envelope instead (see [On the Blockfrost-compatible surface](#on-the-blockfrost-compatible-surface)).

### Your cap is reached: 429

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1796083200
Retry-After: 1036800
```

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "This account's monthly cap is reached.",
  "limit": 100000,
  "reset_at": "2026-12-01T00:00:00Z",
  "scope": "sponsored_cap"
}
```

`limit` is your own cap. `reset_at` and `Retry-After` both point at the start of next month, UTC.

**What to do:** stop sending requests until `reset_at`. Retrying sooner gets the same 429, unless your sponsor raises or removes your cap first.

### Your sponsor's pool is used up: 429

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 1036800
```

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "The shared monthly pool is used up.",
  "reset_at": "2026-12-01T00:00:00Z",
  "scope": "sponsor_pool"
}
```

This 429 carries no number: no `limit` in the body and no `X-RateLimit-*` headers.

**What to do:** stop sending requests until `reset_at`, unless your sponsor's pool is raised first. When both limits are reached, you get the `sponsored_cap` 429.

### Per-second rate limit: 429

Unchanged: `Retry-After: 1` and the usual body, with `limit` set to the per-second rate that applied. Slow down and retry. See [Rate Limits](https://nexus.gerowallet.io/docs/concepts/rate-limits.md#when-you-hit-a-limit).

### Sponsored access is paused: 402

```http theme={null}
HTTP/1.1 402 Payment Required
```

```json theme={null}
{
  "error": "subscription_required",
  "message": "Sponsored access for this account is paused.",
  "reason": "sponsor_inactive"
}
```

There is no `Retry-After`. The message does not say why access is paused, and it does not ask you to subscribe.

**What to do:** do not retry in a loop. Access comes back when the sponsorship resumes; check again every few minutes, or watch the dashboard. If you need access now, you can [get your own plan](#getting-your-own-plan).

### After the sponsorship ends: 402

Once the sponsorship has ended, your account is an account without a plan. Requests get the plain 402, with no `reason`:

```json theme={null}
{
  "error": "subscription_required",
  "message": "An active subscription is required. Subscribe at https://nexus.gerowallet.io/dashboard/billing/"
}
```

**What to do:** [get your own plan](#getting-your-own-plan). Your keys work again once it is active.

### MCP

MCP tool calls follow the same rules and report them inside the tool result (see [MCP Server errors](https://nexus.gerowallet.io/docs/addons/mcp-server.md#errors)). While the sponsorship is paused, a tool call returns:

```json theme={null}
{
  "errorCode": "subscription_required",
  "code": -32006,
  "message": "Sponsored access for this account is paused.",
  "upgradeUrl": "https://nexus.gerowallet.io/dashboard/billing/"
}
```

A paused account gets this answer, not `mcp_addon_required`, unless MCP is turned off on the key itself. The monthly limits answer with `quota_exceeded` (`code` -32002) and a `scope`:

```json theme={null}
{
  "errorCode": "quota_exceeded",
  "code": -32002,
  "message": "This account reached its monthly cap. It resets at 2026-12-01T00:00:00Z.",
  "resetAt": "2026-12-01T00:00:00Z",
  "limit": 100000,
  "scope": "sponsored_cap"
}
```

When the pool is used up, `scope` is `sponsor_pool`, there is no `limit`, and the message is "The sponsored request pool is used up for this month. It resets at" followed by the date. None of these errors names your sponsor's plan. After the sponsorship ends, tool calls are refused as for any account without a plan of its own.

### WebSocket handshake and close

The WebSocket handshake refuses with an HTTP status and a JSON body naming the reason, `{"error":"..."}` (see [Refused connections](https://nexus.gerowallet.io/docs/addons/websockets.md#refused-connections)):

| Status | `error` | When |
| - | - | - |
| 403 | `subscription_inactive` | The sponsorship is paused |
| 403 | `plan_disabled` | The sponsorship has ended and your account has no plan of its own, or the key's WebSocket is turned off (its package is set to None) |
| 403 | `tier` or `plan_disabled` | Without a shared allowance: your sponsor's subscription includes no WebSocket for this key. A key with a package gets `plan_disabled` when your sponsor bought no WebSocket package; a key without one gets `tier` or `plan_disabled` when your sponsor's plan includes no WebSocket connections |
| 429, with `Retry-After: 30` | `concurrency_cap` | Every connection of the shared total is in use |

When the sponsorship pauses or ends, an open session gets one text frame, `{"error":"subscription_inactive"}`, and is then closed with code `1008` and reason `subscription_inactive`. After an end, or after you leave, this happens within about a minute. When the monthly messages run out, the session gets `{"error":"quota_exceeded"}` and is closed with `1008` and reason `quota_exceeded`. Neither frame carries a number.

**What to do:** after a 429, reconnect after `Retry-After`. After `quota_exceeded`, wait for the monthly reset. After a 403 or `subscription_inactive`, do not reconnect in a loop: wait until the sponsorship is active again.

### On the Blockfrost-compatible surface

* Paused: 402 with `{"status_code":402,"error":"Payment Required","message":"Sponsored access for this account is paused."}`.
* Cap or pool: 429 in Blockfrost's `Project Over Limit` envelope, with `Retry-After`. Its `message` is the same sentence as on the native surface. It has no `scope`.

## Rate-limit headers

Your successful responses carry `X-RateLimit-*` headers only when your account has a cap. They then describe your cap, never the pool:

| Header | Meaning for a sponsored key |
| - | - |
| `X-RateLimit-Limit` | Your monthly cap |
| `X-RateLimit-Remaining` | Your cap minus your requests this month |
| `X-RateLimit-Reset` | 00:00 UTC on the 1st of next month, as Unix epoch seconds |

Without a cap there are no `X-RateLimit-*` headers at all. That is not an error.

## WebSocket

Sponsored keys stream market data from `/ws/market` like any key (see [WebSocket Streaming](https://nexus.gerowallet.io/docs/addons/websockets.md)). What they get depends on whether your sponsor's program has a shared WebSocket allowance.

### With a shared allowance

Every key gets WebSocket from one shared total: a number of connections at a time and a number of messages a month (or no message limit). The total is shared by your sponsor's own keys and every account your sponsor pays for.

* **No package is needed on a key.** A key without a WebSocket package connects. A key's own package does not change what it gets.
* **A key set to None is refused.** In the key's Entitlements, **Turn WebSocket off for this key** sets it. Its handshakes then get 403.
* **When every connection is in use**, the next handshake gets 429 with `Retry-After: 30`, whoever holds the open connections. Closing one frees a slot for any key.
* **Every delivered message counts** toward the shared monthly messages. When they run out, sessions close with `quota_exceeded` until the monthly reset.

The API keys page says: "Every key gets WebSocket from", then your sponsor's name and "shared allowance", with the size of the allowance. On the Plan usage card, **WebSocket connections** reads "Up to (a number) at a time, shared". **WebSocket messages** shows a state only: **Available**, **Running low** (80 percent or more used) or **Used up**.

### Without a shared allowance

A sponsored key gets WebSocket from your sponsor's subscription:

* A key that carries a WebSocket package gets that package or your sponsor's package, whichever is smaller, and nothing when your sponsor has no package. A key set to None is refused.
* A key without a package gets the WebSocket your sponsor's plan includes, if any.
* When your sponsor's WebSocket is limited, its connections and monthly messages are one total, shared by your sponsor and every account it pays for. The Plan usage card then shows the WebSocket messages as a state, as above.
* When it is unlimited, your account's connections are counted on their own, up to a number set for your account.

## Pausing, notice and ending

A sponsorship is **Active**, **Ending** (it has an end date), or **Paused**.

### Paused

A sponsorship is paused when your sponsor's program is suspended, or when your sponsor's plan is not active. Nothing ends.

* **What stops:** API requests (the 402 above), MCP tool calls (-32006), new WebSocket connections (403), and open WebSocket sessions, which are closed.
* **What is kept:** your API keys, your team and your usage history.
* **New keys:** on the API keys page, **Create API key** is turned off with "Sponsored access is paused. New keys can be created when it resumes."

When the pause ends, your keys work again with no change on your side.

### Notice and end dates

A sponsorship can have an end date, for example when your sponsor gives notice. The billing page shows it under **Ends**, and in the last 30 days before it the pill and the banner say so. A notice can be withdrawn before its date. Until the date, everything works as before. At the end date and time, requests from your keys start getting the plain 402.

### Ended

A sponsorship ends at its end date, when your sponsor ends it, when you leave it, or when you get a plan of your own. An end made at your sponsor's request takes effect within about a minute. Once it has ended:

* Requests get the plain 402 shown in [After the sponsorship ends](#after-the-sponsorship-ends-402), MCP tool calls are refused as for an account without a plan, and open WebSocket sessions close with `subscription_inactive` within about a minute.
* Your keys, your team and your usage history stay.
* For 30 days, unless you have a plan of your own, the owner's Overview shows "Sponsorship from (your sponsor) ended on (a date)", with **Get your own plan**.

To be sponsored again, ask your sponsor: the Nexus team adds accounts to a program at the sponsor's request.

## Getting your own plan

The account owner can get a plan at any time: **Billing**, **Get your own plan**. The plan picker on a sponsored account's billing page offers no trial.

When your own plan becomes active, the sponsorship ends and your keys keep working on your plan's limits. Each key keeps only the add-ons and WebSocket package your plan includes. A sponsorship cannot start on an account that has an active plan of its own.

## Leaving a sponsorship

Only the account owner can leave: **Billing**, **Danger zone**, **Leave sponsorship**. You confirm by typing your sponsor's name. Requests from your keys are rejected within about a minute. Your keys and usage history stay, and work again once you have a plan.

## Team members

Members of a sponsored account who are not its owner see the same pill, banners and billing card as the owner. The billing card is read only and says "Only the account owner can leave the sponsorship or get a plan for this account." The banners do not offer **Get your own plan**, and the ending banner asks the member to ask the account owner to get a plan. Members whose role lets them manage keys create keys as usual. The one-time "ended" notice is shown to the owner only.

## Privacy

**What you see of your sponsor:** its name, its contact email when it gave one, what the sponsorship gives you (add-ons, rate limit, key limit, WebSocket and the size of a shared WebSocket allowance), your own cap and your own usage, the pool as a state, and the dates on which access ends or may pause. Your account's own plan data also carries the tier of your sponsor's plan: the subscription, plan status and API key quota that the dashboard reads for your account return it in their `tier` field, while the subscription and plan status give the plan's name as "Sponsored".

**What you do not see:** your sponsor's price or payment state, any figure of its pool, the other accounts it pays for, or why access pauses or ends.

**What your sponsor can learn:** your requests count in your sponsor's monthly request total, and on a shared WebSocket total your connections and messages count with everyone else's. The Nexus team, who run the program for your sponsor, see each sponsored account's owner email, its requests this month, its cap and when its keys were last used, and can share these usage figures with your sponsor. Your billing page states what your sponsor sees: "Your account's usage. Not your key secrets, the content of your requests or your billing." Your sponsor cannot sign in to your account, and never gets your key secrets, the content of your requests or your billing.

## Next steps

> [card] [Rate Limits](https://nexus.gerowallet.io/docs/concepts/rate-limits.md)
>
> Monthly quotas, per-second limits and their headers

> [card] [Error Handling](https://nexus.gerowallet.io/docs/concepts/error-handling.md)
>
> How Nexus reports API errors

> [card] [WebSocket Streaming](https://nexus.gerowallet.io/docs/addons/websockets.md)
>
> Live market data over STOMP

> [card] [MCP Server](https://nexus.gerowallet.io/docs/addons/mcp-server.md)
>
> Nexus tools for AI agents


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.