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

# GET /v1/currency — 用于美元价格换算的汇率

> 获取 CSBoard 支付流程所使用的以美元为基准的汇率表。将任意 price_usd 乘以目标货币汇率，即可得到当地货币价格。

CSBoard API 中所有价格均以美元计价。currency 端点返回与站点自身支付与展示流程相同的汇率表，为您提供一致的换算层，用于向用户展示本地货币价格。汇率主要币种来源于 OpenExchangeRates，RUB 来源于俄罗斯中央银行，并缓存约一小时。

**需要身份验证。** 请将密钥作为 `Authorization: Bearer csb_pub_...` 发送。

## 参数

此端点不接受任何查询参数。

## 响应字段

<ResponseField name="base" type="string" required>
  始终为 `"USD"`。所有汇率均相对于 1 美元表示。
</ResponseField>

<ResponseField name="rates" type="object" required>
  ISO 4217 货币代码到其相对美元汇率（每 1 美元等于多少该货币单位）的映射。例如：`{ "USD": 1, "EUR": 0.92, "RUB": 78.4, "GBP": 0.79 }`。
</ResponseField>

<ResponseField name="updated_at" type="datetime" required>
  汇率表上次刷新时的 ISO 8601 时间戳。
</ResponseField>

<ResponseField name="rub_source" type="string">
  RUB 汇率的来源标识，例如 `"cbr"`（俄罗斯中央银行）。
</ResponseField>

<ResponseField name="base_source" type="string">
  非 RUB 汇率的来源标识，例如 `"openexchangerates"`。
</ResponseField>

## 价格换算

要将 `price_usd` 值以本地货币显示，请将其乘以对应汇率：

```
local_price = price_usd × rates["EUR"]
# 例如 14.37 USD × 0.92 = 13.22 EUR
```

由于汇率表缓存约 1 小时，请在应用启动时获取一次，并定期刷新，而非对每个商品都调用此端点。

## 示例请求

```bash theme={null}
curl https://csboard.com/v1/currency \
  -H "Authorization: Bearer csb_pub_..."
```

## 示例响应

```json theme={null}
{
  "base": "USD",
  "rates": {
    "USD": 1,
    "EUR": 0.92,
    "RUB": 78.4,
    "GBP": 0.79
  },
  "updated_at": "2026-06-29T17:00:00Z",
  "rub_source": "cbr",
  "base_source": "openexchangerates"
}
```

## 错误代码

| HTTP 状态码 | 代码                    | 含义                                    |
| -------- | --------------------- | ------------------------------------- |
| 401      | `unauthorized`        | API 密钥缺失或无效。                          |
| 429      | `rate_limit_exceeded` | 超过 30 次/分钟。在重试前请检查 `Retry-After` 响应头。 |

<Tip>
  请在客户端缓存 rates 响应，每小时刷新不超过一次。汇率约每小时更新一次，更频繁地轮询不会带来更新鲜的数据，反而会消耗您的速率限制额度。
</Tip>


## OpenAPI

````yaml GET /currency
openapi: 3.1.0
info:
  title: CSBoard API
  version: 1.0.0
  description: >-
    Market data over the CSBoard marketplace — live listings, floats, stickers,
    minAsk prices, FX rates — plus opt-in buying straight from your balance.
    Free to read, key-gated, built for automation.
  contact:
    name: CSBoard
    url: https://csboard.com/docs
servers:
  - url: https://csboard.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Status
    description: Liveness and freshness probes.
  - name: Market data
    description: Read the live catalog, prices, and FX rates.
  - name: Trading
    description: Buy listings from your CSBoard balance. Opt-in, key-gated.
  - name: Account
    description: Your balance, settled funds, and trading status.
paths:
  /currency:
    get:
      tags:
        - Market data
      summary: FX rates (USD base)
      description: >-
        FX rates with USD as the base. Every price in this API is USD — use this
        to convert to a local currency. Same rate table the site and payment
        flows use (cached ~1h).
      operationId: getCurrency
      responses:
        '200':
          description: Current FX rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Currency'
              example:
                base: USD
                rates:
                  USD: 1
                  EUR: 0.92
                  RUB: 78.4
                  GBP: 0.79
                updated_at: '2026-06-29T17:00:00Z'
                rub_source: cbr
                base_source: openexchangerates
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Currency:
      type: object
      properties:
        base:
          type: string
          example: USD
        rates:
          type: object
          additionalProperties:
            type: number
          description: Currency code → units per 1 USD.
        updated_at:
          type: string
          format: date-time
        rub_source:
          type: string
        base_source:
          type: string
      required:
        - base
        - rates
        - updated_at
    Error:
      type: object
      description: >-
        All errors return { code, detail }. Some carry extra fields (e.g.
        price_moved adds current_total_usd, insufficient_balance adds
        required_usd/current_usd).
      properties:
        code:
          type: string
          description: >-
            Machine-readable error code, e.g. rate_limit_exceeded,
            trading_not_enabled, price_moved.
        detail:
          type: string
          description: Human-readable explanation.
      required:
        - code
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: Missing or invalid API key.
    RateLimited:
      description: Rate limit exceeded. Includes a Retry-After header.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limit_exceeded
            message: Too many requests.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send your key as a Bearer token on every request: `Authorization: Bearer
        csb_pub_...`. Generate keys in your CSBoard profile.

````