## Currency settings (`settings`)

Admin settings for the currency table (enabled, rate, rounding), the base currency and the default for new users; confirming the pre-upgrade accounting currency after upgrading from an old version.

Authentication: Admin only · Docs: https://www-sa2.kuxitong.com/en/docs/api/settings

### GET `/api/v2/settings/currencies`

Get currency settings · Authentication: Admin only

```sh
curl "https://panel.example.com/api/v2/settings/currencies" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/settings/currencies`

Create currency · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | string | Yes | Currency code (ISO 4217, 3 uppercase letters). |
| `enabled` | boolean |  | Whether enabled |
| `minor_digits` | integer |  | Display decimals: 2 = two decimals, 0 = none (JPY, KRW, ...); with 0, converted prices round to whole units and x99 tiers to ..99 or ..9 whole units. Amount fields still count 1/100 of the major unit. Omitted on create = ISO 4217 default (0 for zero-decimal currencies, else 2). Values: [0,2] |
| `name` | string | Yes | Name |
| `rate` | string |  | 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places. |
| `rate_mode` | string |  | Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand. Values: ["auto","manual"] |
| `rounding` | string |  | Price rounding: none, or x99 = tiered: try .99, then .x9, and take the first whose premium over the exact converted price is at most 10%; if both exceed it, keep the exact price. Values: ["none","x99"] |
| `symbol` | string | Yes | Display symbol such as ¥, US$, HK$. |

```sh
curl -X POST "https://panel.example.com/api/v2/settings/currencies" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"USD","name":"美元","rate":"7.10000000","rate_mode":"manual","rounding":"x99","symbol":"US$"}'
```

### PUT `/api/v2/settings/currencies`

Update currency settings · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `base_currency` | string |  | Base currency: reports are converted into it; locked after the first order. |
| `default_currency` | string |  | Default account currency for new users. |
| `fx_source` | string |  | Exchange rate source. |

```sh
curl -X PUT "https://panel.example.com/api/v2/settings/currencies" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_currency":"USD"}'
```

### GET `/api/v2/settings/currencies/fx/preview`

Preview exchange rates · Authentication: Admin only

```sh
curl "https://panel.example.com/api/v2/settings/currencies/fx/preview" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/settings/currencies/fx/refresh`

Fetch exchange rates now · Authentication: Admin only

```sh
curl -X POST "https://panel.example.com/api/v2/settings/currencies/fx/refresh" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/settings/currencies/{code}`

Update currency · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `enabled` | boolean |  | Whether enabled |
| `minor_digits` | integer |  | Display decimals: 2 = two decimals, 0 = none (JPY, KRW, ...); with 0, converted prices round to whole units and x99 tiers to ..99 or ..9 whole units. Amount fields still count 1/100 of the major unit. Omitted on create = ISO 4217 default (0 for zero-decimal currencies, else 2). Values: [0,2] |
| `name` | string |  | Name |
| `rate` | string |  | 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places. |
| `rate_mode` | string |  | Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand. Values: ["auto","manual"] |
| `rounding` | string |  | Price rounding: none, or x99 = tiered: try .99, then .x9, and take the first whose premium over the exact converted price is at most 10%; if both exceed it, keep the exact price. Values: ["none","x99"] |
| `symbol` | string |  | Display symbol such as ¥, US$, HK$. |

```sh
curl -X PUT "https://panel.example.com/api/v2/settings/currencies/{code}" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rate":"7.20000000","rate_mode":"manual"}'
```

### DELETE `/api/v2/settings/currencies/{code}`

Delete currency · Authentication: Admin only

```sh
curl -X DELETE "https://panel.example.com/api/v2/settings/currencies/{code}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/settings/currency-legacy`

Get legacy currency confirmation · Authentication: Admin only

```sh
curl "https://panel.example.com/api/v2/settings/currency-legacy" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/settings/currency-legacy`

Confirm the accounting currency before the upgrade · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `currency` | string | Yes | The accounting currency before the upgrade (ISO 4217); becomes the base currency and is stamped on existing accounts and orders (amounts are not converted). |

```sh
curl -X POST "https://panel.example.com/api/v2/settings/currency-legacy" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"USD"}'
```

Currency settings object:

| Field | Type | Required | Description |
|---|---|---|---|
| `base_currency` | string |  | Base currency: reports are converted into it; locked after the first order. |
| `base_locked` | boolean |  | Orders exist, so the base currency can no longer be changed. |
| `can_reselect` | boolean |  | Whether it can be (re)selected now: pending, or confirmed within 7 days with no new orders since the upgrade. |
| `code` | string | Yes | Currency code (ISO 4217, 3 uppercase letters). |
| `currencies` | Currency[] |  | Currency table (base currency first). |
| `currency` | string | Yes | The accounting currency before the upgrade (ISO 4217); becomes the base currency and is stamped on existing accounts and orders (amounts are not converted). |
| `deadline` | string |  | Deadline for reselecting (7 days after upgrade). |
| `default_currency` | string |  | Default account currency for new users. |
| `enabled` | boolean |  | Whether enabled |
| `fetched_at` | string |  | Time the rates were fetched. |
| `fx_fetched_at` | string |  | Last time the rate source returned this currency; auto cannot be selected while null. |
| `fx_source` | string |  | Exchange rate source. |
| `fx_sources` | string[] |  | Available exchange rate sources. |
| `max_deviation_pct` | integer |  | Maximum percentage a refreshed auto rate may deviate from the old rate (beyond it the rate is rejected). |
| `minor_digits` | integer |  | Display decimals: 2 = two decimals, 0 = none (JPY, KRW, ...); with 0, converted prices round to whole units and x99 tiers to ..99 or ..9 whole units. Amount fields still count 1/100 of the major unit. Omitted on create = ISO 4217 default (0 for zero-decimal currencies, else 2). Values: [0,2] |
| `name` | string | Yes | Name |
| `rate` | string |  | 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places. |
| `rate_mode` | string |  | Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand. Values: ["auto","manual"] |
| `rate_updated_at` | string |  | Last time the rate changed. |
| `rates` | object |  | Currency → 1 unit = ? base currency (decimal string); includes currencies not in the table, base is 1. |
| `rejected` | string[] |  | Currencies whose new rate was not applied because it deviated more than max_deviation_pct from the old rate (auto-mode rows; the old rate and timestamp are kept). Empty if none. |
| `rounding` | string |  | Price rounding: none, or x99 = tiered: try .99, then .x9, and take the first whose premium over the exact converted price is at most 10%; if both exceed it, keep the exact price. Values: ["none","x99"] |
| `saved` | string[] |  | Currencies whose rate was saved this time (rows in auto mode). |
| `source` | string |  | Exchange rate source used this time. |
| `state` | string |  | unset = not yet judged, pending = awaiting confirmation, confirmed, auto_cny = set to CNY automatically, none = fresh install. Values: ["unset","pending","confirmed","auto_cny","none"] |
| `symbol` | string | Yes | Display symbol such as ¥, US$, HK$. |
| `unopened_users` | integer |  | Tenants without an account row yet: they are priced in the new-user default currency and counted in its user_count; changing the default currency moves them too. |
| `user_count` | integer |  | Number of users whose account currency is this one. |
