> AI 에이전트용: 단계별 설정 안내 — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), 문서 인덱스 — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# 요금제 및 계정

모델 가격, 입금 및 출금 수수료, GNK 환율. 키 기반 계정 API: 잔액, 일별 및 모델별 지출, 거래 내역, 충전 내역.

## 모델 가격

가격에는 플랫폼 수수료 10%가 이미 포함되어 있습니다. 실시간 값은 `GET /api/pricing`에서 확인할 수 있습니다 (키 불필요).

| `model` | 입력, 100만 토큰당 $ | 출력, 100만 토큰당 $ | 토큰당 nGNK: 입력 / 출력 |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | $0.008349 | $0.02505 | 33 / 99 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | $0.008349 | $0.02505 | 33 / 99 |
| `zai-org/GLM-5.3-Flash` | $0.008349 | $0.02505 | 33 / 99 |

- 요청 비용 = 입력 토큰 × 입력 가격 + 출력 토큰 × 출력 가격. 모델 추론은 출력 토큰으로 계산됩니다.
- 청구는 GNK로 이루어집니다 (1 GNK = 10⁹ `nGNK`). 달러 가격은 GNK 환율 $0.253을 기준으로 합니다.
- 요청 전에 게이트웨이가 잔액과 예상 비용을 대조합니다. 부족하면 `402 insufficient_funds`가 반환됩니다.
- 등록 후 계정에 0.1 GNK가 지급됩니다 — 입력 가격 기준 약 3M 토큰 상당입니다.

## 수수료

| 작업 | 수수료 | 비고 |
| --- | --- | --- |
| 모델 요청 수수료 | 10% | 위 가격에 이미 포함되어 있습니다. |
| GNK 충전 | 무료 | `memo`를 포함하여 게이트웨이 주소로 전송하세요. 자동으로 반영됩니다. |
| USDT 충전 | 5% → 2.5% | OxaPay를 통한 결제. 금액이 클수록 수수료가 낮아집니다 — [USDT 수수료 티어](https://gate.joingonka.ai/ko/docs/billing#usdt-tiers). |
| Ethereum에서 WGNK 충전 | 1% | Gonka로 전송할 때의 Ethereum 네트워크 가스를 충당합니다. |
| GNK 출금 | 5% | 대시보드에서만 가능하며 최소 1 GNK부터입니다. |
| GNK 환율 | $0.253 | 충전 및 달러 가격 계산에 사용됩니다. 자동으로 업데이트됩니다. |

### USDT 수수료 티어

요율은 충전 금액에 따라 달라지며, 임계값은 이상입니다:

| 충전 금액 | 수수료 |
| --- | ---: |
| $0부터 | 5% |
| $25부터 | 4.5% |
| $50부터 | 4% |
| $100부터 | 3.5% |
| $250부터 | 3% |
| $500부터 | 2.75% |
| $1000부터 | 2.5% |

## 계정 API

잔액, 지출 및 충전은 모델 요청과 동일한 키 (`Authorization: Bearer jg-…`)로 이용할 수 있습니다. 이러한 요청은 토큰을 소비하지 않습니다.

오류: 키 없음 — `401 authentication_error`, 잘못된 매개변수 — `400 validation_error`, API 키로 대시보드 라우트 접근 — `403 forbidden`.

### GET `/api/balance`

현재 잔액.

| 필드 | 설명 |
| --- | --- |
| `balance_ngonka` | nGNK 잔액 — 정밀도를 유지하기 위해 문자열로 |
| `balance_usd` | 현재 환율 기준 달러 잔액 |
| `cost_per_token_ngonka` | 권장 모델의 입력 토큰 가격 (수수료 포함), nGNK |
| `tokens_remaining` | 이 가격에서 잔액으로 처리할 수 있는 입력 토큰 수 — 추정치 |

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

### GET `/api/usage`

일별 사용량: 요청, 토큰, 비용.

- `period` — `day`, `week`, `month`, `quarter`, 기본값은 `month`.
- 또는 `from`과 `to`를 `YYYY-MM-DD` 형식으로 동시에 지정, 최대 92일까지(양끝 포함) — 이 경우 응답은 `period: custom`.
- `tz` — 분 단위 오프셋, 브라우저의 `getTimezoneOffset()`과 같은 형식: UTC+3이면 `-180`. 생략 시 UTC.

응답은 `date, requests, tokens, costNgonka` 필드를 가진 일별 배열입니다. 요청 상세 레코드는 90일간 보관됩니다.

```bash
curl -s "https://gate.joingonka.ai/api/usage?period=week&tz=-180" \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

### GET `/api/usage/by-model`

모델별 사용량: `models`에 합계, `series`에 '기간 × 모델' 시리즈 — `period=day` 지정 시 시간 단위, 그 외에는 일 단위. 파라미터는 `/api/usage`와 동일.

### GET `/api/usage/by-key`

키별 사용량 — `keys`. 파라미터는 `/api/usage`와 동일.

### GET `/api/transactions`

거래 내역: 충전, 요청에 따른 차감, 보너스, 출금.

- `limit` — 최대 200, 기본값 50; `offset` — 오프셋.
- `type` — 필터: `DEPOSIT_USDT`, `DEPOSIT_GNK`, `DEPOSIT_FIAT`, `INFERENCE`, `REFERRAL_REWARD`, `BONUS`, `WITHDRAWAL`.
- `from`과 `to` — 날짜, 종료일 포함.

응답은 `id, type, amountNgonka, feeNgonka, description, createdAt` 필드를 가진 레코드와 총 개수 `total`입니다. `INFERENCE`이(가) 90일보다 오래된 레코드는 하루 단위로 합쳐집니다.

### GET `/api/deposits`

충전만. 파라미터 `limit`, `offset`, `from`, `to`는 거래 내역과 동일; 응답에 `total`이 있습니다.

### POST `/api/deposit/gnk`

GNK 충전 정보: `address`와 `memo`. 이 `memo`를 붙여 GNK를 이 주소로 보내면 자동으로 반영됩니다.

### GET `/api/deposit/usdt/rate`

USDT 충전 환율과 수수료: `gnk_usd_price`, `fee_percent`, `fee_tiers`.

### POST `/api/deposit/usdt`

USDT 결제용 청구서: 본문 `{"amount": 25}` — 1에서 10000까지의 달러 금액; 응답에 `payment_url`. USDT 수신이 일시 중단된 경우 `503`.

### GET `/api/pricing`

키 없이 확인하는 가격과 수수료: `models[]`, `deposit_usdt_fee_tiers`, GNK 환율, 가입 보너스.

### 대시보드 전용

계정 관리는 [gate.joingonka.ai/dashboard](https://gate.joingonka.ai/dashboard) 대시보드에서 합니다. 이 경로들은 연동용이 아니며, 일부는 API 키에 `403 forbidden`를 반환합니다:

- API 키 — [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys);
- GNK 출금 — 최소 1 GNK;
- 카드 충전 및 WGNK 발신 주소;
- 프로모 코드;
- 추천 프로그램 및 메일 설정.