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

# 身份验证与限制

> API key 使用、端点格式、速率限制和连接数限制

## RPC 身份验证

所有 OrbitFlare RPC 请求通过在端点 URL 上附加许可证密钥作为查询参数来进行身份验证。

```bash theme={null}
curl -X POST "https://mainnet.rpc.orbitflare.com?api_key=YOUR_LICENSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBlockHeight"
  }'
```

<Tip>
  你的 RPC 许可证密钥随 OrbitFlare 服务订阅一同提供。你可以在 [OrbitFlare 控制面板](https://orbitflare.com/dashboard) 的**许可证**部分找到它。
</Tip>

## Customer API 身份验证

[Customer API](/api-documentation/welcome) 使用不同的身份验证方式。通过 `X-ORBIT-KEY` HTTP 头传递你的 API key：

```bash theme={null}
curl -X GET https://api.orbitflare.com/customer/v2/licenses \
  -H "X-ORBIT-KEY: YOUR_API_KEY"
```

Customer API v2 还支持通过设备流程或钱包签名认证获得的 Bearer token 身份验证。详情请参阅 [Customer API 文档](/api-documentation/welcome)。

## RPC 端点

OrbitFlare 提供地理分布式 RPC 端点，你可以将请求路由到离你的用户或基础设施最近的区域。URL 格式为：

```
https://{region}.rpc.orbitflare.com?api_key=YOUR_API_KEY
```

将 `{region}` 替换为下列区域代码之一。

### 可用区域

<Tabs>
  <Tab title="美国">
    | 城市  | 区域代码  | 端点                                                    |
    | --- | ----- | ----------------------------------------------------- |
    | 阿什本 | `ash` | `https://ash.rpc.orbitflare.com?api_key=YOUR_API_KEY` |
    | 纽约  | `ny`  | `https://ny.rpc.orbitflare.com?api_key=YOUR_API_KEY`  |
    | 洛杉矶 | `la`  | `https://la.rpc.orbitflare.com?api_key=YOUR_API_KEY`  |
    | 盐湖城 | `slc` | `https://slc.rpc.orbitflare.com?api_key=YOUR_API_KEY` |
  </Tab>

  <Tab title="欧洲">
    | 城市      | 区域代码   | 端点                                                     |
    | ------- | ------ | ------------------------------------------------------ |
    | 阿姆斯特丹   | `ams`  | `https://ams.rpc.orbitflare.com?api_key=YOUR_API_KEY`  |
    | 法兰克福    | `fra`  | `https://fra.rpc.orbitflare.com?api_key=YOUR_API_KEY`  |
    | 伦敦      | `lon`  | `https://lon.rpc.orbitflare.com?api_key=YOUR_API_KEY`  |
    | 都柏林     | `dub`  | `https://dub.rpc.orbitflare.com?api_key=YOUR_API_KEY`  |
    | 立陶宛希奥利艾 | `siau` | `https://siau.rpc.orbitflare.com?api_key=YOUR_API_KEY` |
  </Tab>

  <Tab title="亚太地区">
    | 城市  | 区域代码  | 端点                                                    |
    | --- | ----- | ----------------------------------------------------- |
    | 东京  | `tok` | `https://tok.rpc.orbitflare.com?api_key=YOUR_API_KEY` |
    | 新加坡 | `sgp` | `https://sgp.rpc.orbitflare.com?api_key=YOUR_API_KEY` |
  </Tab>
</Tabs>

### 主网端点（自动路由）

如果你不需要将请求固定到特定区域，请使用主网端点。OrbitFlare 会自动将每个请求定向到最近的可用区域。

```
https://mainnet.rpc.orbitflare.com?api_key=YOUR_API_KEY
```

<Note>
  建议大多数场景使用主网端点。它提供最低延迟，无需你手动管理区域选择。
</Note>

## WebSocket 端点

WebSocket 连接使用相同的区域代码，采用 `wss://` 协议：

```
wss://{region}.rpc.orbitflare.com?api_key=YOUR_API_KEY
```

自动路由的 WebSocket 连接：

```
wss://mainnet.rpc.orbitflare.com?api_key=YOUR_API_KEY
```

身份验证通过相同的 `api_key` 查询参数处理。

## Devnet

OrbitFlare 提供专用的 Devnet 端点，用于开发和测试：

```
https://devnet.rpc.orbitflare.com?api_key=YOUR_API_KEY
```

<Warning>
  Devnet 端点连接到 Solana Devnet。请勿将其用于生产工作负载。Devnet 代币没有货币价值。
</Warning>

## 各方案速率限制

每个方案定义了最大**每秒请求数 (RPS)** 和**每秒交易数 (TPS)**。

| 方案        | 每秒请求数 (RPS) | 每秒交易数 (TPS) |
| --------- | :---------: | :---------: |
| Free      |      10     |      1      |
| Developer |      50     |      10     |
| Growth    |     200     |      75     |
| Scale     |     400     |     150     |
| Pro       |     600     |     200     |
| Dedicated |     无限制     |     无限制     |

<AccordionGroup>
  <Accordion title="超过速率限制会怎样？">
    超过方案 RPS 或 TPS 限制的请求将收到 HTTP `429 Too Many Requests` 响应。请在你的客户端中实现指数退避策略来优雅地处理这种情况。
  </Accordion>

  <Accordion title="是否有月度额度或请求上限？">
    没有。OrbitFlare 不设置月度额度限制或请求上限。只要在你方案的每秒速率限制内，你可以发送无限总请求。
  </Accordion>
</AccordionGroup>

<Note>
  OrbitFlare 方案**没有额度限制**——只要在方案的每秒速率层级内，你可以发送无限请求。不会产生意外的超额费用。
</Note>

## 数据流连接限制

连接限制与你的 RPC 速率限制层级无关，按 IP 地址在所有流式传输接口上独立执行。

### gRPC（Jetstream / Yellowstone）

| 限制           | 数值                  |
| ------------ | ------------------- |
| 每个 IP 的并发连接数 | **50**              |
| 每个连接的订阅数     | 无限制                 |
| 空闲连接超时       | 10 分钟（使用 ping 保持连接） |

50 个连接上限在来自同一 IP 地址的所有 gRPC 端点（Jetstream 和 Yellowstone）之间共享。无论你连接到哪个区域，此限制均适用。

<Note>
  专用 gRPC 节点不受共享连接限制的约束。如果你需要超过 50 个并发 gRPC 连接，请联系团队了解专用 gRPC 节点。
</Note>

**保持连接活跃**

云负载均衡器和代理（包括 Cloudflare）可能会在约 10 分钟后关闭空闲的 gRPC 流。每 30 秒发送一次 ping 以防止断开连接：

```typescript theme={null}
const pingRequest: SubscribeRequest = {
  ping: { id: 1 },
  accounts: {},
  accountsDataSlice: [],
  transactions: {},
  transactionsStatus: {},
  blocks: {},
  blocksMeta: {},
  slots: {},
  entry: {},
};

setInterval(() => {
  stream.write(pingRequest, (err) => {
    if (err) console.error("Ping 失败:", err);
  });
}, 30_000);
```

**超过限制时会发生什么**

当你的 IP 已有 50 个活跃的 gRPC 连接并尝试打开新连接时，服务器将返回 gRPC `RESOURCE_EXHAUSTED` 状态：

```
StatusCode: RESOURCE_EXHAUSTED
Message: connection limit exceeded
```

在打开新流之前请关闭未使用的流。在 `RESOURCE_EXHAUSTED` 错误后重新连接时，请实现指数退避策略。

### WebSocket

| 限制           | 数值          |
| ------------ | ----------- |
| 每个 IP 的并发连接数 | **50**      |
| 每个连接的订阅数     | 因方案而异       |
| 空闲连接超时       | 无消息交换 60 秒后 |

WebSocket 连接使用相同的每 IP 50 个并发连接限制。没有任何消息交换超过 60 秒的空闲连接将被服务器关闭。

**超过限制时会发生什么**

超出限制后尝试的新 WebSocket 连接将被以 `1008 Policy Violation` 关闭代码拒绝：

```
WebSocket closed: 1008 Policy Violation - connection limit exceeded
```

<AccordionGroup>
  <Accordion title="可以提高连接数限制吗？">
    50 个连接限制适用于所有共享方案。如果你的工作负载需要更多并发流连接，**专用 gRPC 节点**或**专用 RPC 节点**将完全消除共享限制。请在 [Discord](https://discord.gg/orbitflare) 上联系团队讨论选项。
  </Accordion>

  <Accordion title="限制是按区域还是全局的？">
    限制按 IP 地址在所有区域全局执行。单个 IP 在法兰克福有 30 个连接、在纽约有 20 个连接，则已达到 50 个连接上限。
  </Accordion>

  <Accordion title="如何处理重新连接？">
    在连接错误后重新连接时，使用指数退避策略。从 1 秒延迟开始，每次失败尝试后加倍，最大为 30 秒。在重新连接之前，务必干净地关闭流，以避免耗尽你的连接配额。
  </Accordion>
</AccordionGroup>