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

# 交付 OpenAPI

> 如何将 BlockDB 中的数据封装成高性能的 OpenAPI 供下游业务调用

***

Chaintable 平台提供了全托管的 OpenAPI 功能，支持将用户编写的计算函数（Functions）直接发布为标准的 HTTP 服务，方便下游业务系统直接调用。

***

## 网关与执行架构

OpenAPI 的调用架构在逻辑上分为两层：

* **产品业务端 OpenAPI 网关**：负责统一接收用户的请求，执行**鉴权**、**限流计费**以及**日志记录**。
* **SyncInvoker（独立部署）**：网关验证通过后，将请求转发给独立部署的 SyncInvoker 集群，实际**执行特定的 Function 并返回数据结果**。独立部署的设计能够有效避免平台内部其他业务对 API 调用产生干扰。

***

## 接口调用规范

### 请求示例

用户通过标准的 `POST` 请求调用特定 endpoint，Header 需要承载平台信息（如 AccessKey）：

```bash theme={null}
curl -X POST '[https://openapi.chaintable.com/v1/function/](https://openapi.chaintable.com/v1/function/){function_id}' \
    -H 'accept: application/json' \
    -H 'AccessKey: YOUR_ACCESSKEY' \
    -H 'Content-Type: application/json' \
    -d '[
            "value1",
            123
     ]'

```

* **Endpoint 路由**：不同 function 在逻辑上对应不同的 endpoint，便于统计和归因。
* **参数数组化**：function 的参数本质上是**数组（Array）形式**，这是平台的特性。目前参数定义是软限制，内部不需要再做额外的字典映射。

### 成功返回 (HTTP 200)

接口保持函数原生的返回形态，不对数据做二次壳协议包裹：

```python theme={null}
200 OK
Content-Type: application/json
{
    "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "total_volume_usd": 86421.50
}

```

### 错误返回 (HTTP 5xx / 4xx)

当调用失败时，使用标准的 HTTP 状态码标识失败，并在 JSON 响应体中提供具体的平台错误原因：

```python theme={null}
504 Gateway Timeout
Content-Type: application/json
{     
    "code": "function_timeout", 
    "message": "Execution exceeded the time limit." 
}

```

***

## 用量计费与额度限制

### 1. 计费单位 (Compute Units)

* **计算公式**：单次函数执行按实际执行时间计算用量，`1 unit = 1 ms`。
* **计费保护**：单次请求最低消耗 `100 units`。
* **责任划分**：**系统错误不消耗 unit**。除非明确是“用户错误”，否则其余情况都属于系统错误，不予计费。

### 2. 扣减机制

平台使用 **Redis** 作为计费的唯一事实源。每个账号在 Redis 中维护两个实时计数器：

* `monthly`（月度额度）：月度 unit 随用户套餐账单周期重置，不同套餐的月度额度和额外购买的 addon 额度不能混合。
* `addon`（加油包额度）：额外购买 addon 时增加。

**扣减顺序**：消费时优先消耗 `monthly` 计数器，扣减完毕后再消耗 `addon` 计数器。所有的 unit 读取和变更都直接以 Redis 的操作结果为准。此外，该数据会同步备份到持久化的权益表（`account_openapi_quota`）中。

### 3. 日志审计

所有访问都会产生日志（包含访问基本信息与 unit 消耗信息），并写入 **Elasticsearch (ES)**，用以支撑后续的统计和审查需求。

### 4. 限制阈值

* **单次请求维度**：超时时间硬性限制为 **5 秒**。
* **账号维度**：实施严格的账号级 **RPS（每秒请求数）限制** 以及 **Units 总量限制**。

***

## 全球套餐标准

| 套餐算力等级      | 包含月度算力额度 (Compute Units) | 额外购买单价 (每 1M Units) | 每秒请求限制 (Requests per second) |
| ----------- | ------------------------ | ------------------- | ---------------------------- |
| **\$0**     | 1M units                 | -                   | 5 RPS                        |
| **\$960**   | 200M units               | \$8                 | 100 RPS                      |
| **\$2,880** | 600M units               | \$6.5               | 400 RPS                      |
| **\$9,600** | 2B units                 | \$5                 | 1,600 RPS                    |