> For the complete documentation index, see [llms.txt](https://docs.goodcrypto.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goodcrypto.app/goodcryptox-ko/goodcryptox-3.0/api.md).

# API

내가 만든 프로그램에서 goodcryptoX의 로컬 API로 읽고 거래해요. 키와 한도는 AI 에이전트와 같아요.

내 프로그램은 goodcryptoX의 API를 통해 연결한 거래소에서 읽고 거래할 수 있어요. API는 OpenAPI 문서로 설명돼요. 프로그램은 AI 에이전트와 같은 키, 권한, 한도를 써요([키와 한도](https://docs.goodcrypto.app/goodcryptox-ko/goodcryptox-3.0/ai-agents.md#keys-and-limits)).

`POST /api/v1/accounts/{id}/check`(MCP `check_api_key`)는 카드의 **다시 확인**과 같이 Binance, Bybit 또는 Bybit EU 계정의 API 키 권한을 다시 읽습니다.

숫자는 각 거래의 통화로 와요. 가격과 금액은 마켓의 호가 통화, PnL은 그 행이 가리키는 자산, 크레딧과 `GET /api/v1/portfolio` 응답은 USD, 키의 한도는 설정할 때의 통화예요. `GET /api/v1/rates` 응답에는 기준 통화와 1 USD당 환율이 있어서, goodcryptoX처럼 숫자를 보여 줄 수 있어요.

MCP 도구 `instruments`와 `GET /api/v1/instruments?venue=…`에는 각 마켓의 알려진 24시간 거래량(호가 통화 기준 금액)과 가격 변동률(퍼센트), 그리고 거래소가 보내는 경우 현재가도 포함돼요. API는 [토픽 경로](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/runtime/api.md#the-socket)를 통해 `instrument-stats/<venue>`도 제공해요. 이 수치는 계속 십진수 문자열로 전달돼요. 거래량과 변동률에서 null은 이전에 받은 값을 유지해요. 선택 항목인 `invalidate`에는 지울 값을 지정해요. `lastPrice`가 없으면 호환성을 위해 이전 가격을 유지하고, 명시적으로 null이 전달되면 가격을 지워요.

**설정 › MCP & API**에서 키를 만들어요([방법](https://docs.goodcrypto.app/goodcryptox-ko/goodcryptox-3.0/ai-agents.md#connect-any-mcp-app-or-program)). 그러면 연결 블록의 **API** 쪽에 세 줄이 나오고, 각각 복사 아이콘이 있어요. **주소**, **키**, 그리고 고른 키가 들어간 채로 프로그램이 요청마다 보내는 헤더예요. `Authorization: Bearer <your key>`. 헤더 옆의 복사 아이콘은 전체를 복사해요.

<details>

<summary>API 요청 예시</summary>

프로그램이 접근하는 오리진을 `GCX_URL`로 설정하고 환경에 `GCX_KEY`를 넣어요. 이 예시는 계정을 읽어요.

```sh
curl --fail-with-body -H "Authorization: Bearer $GCX_KEY" "$GCX_URL/api/v1/accounts"
```

OpenAPI 문서는 `$GCX_URL/api/v1/openapi.json`에 있어요. 프로그램은 같은 Bearer 헤더로 문서를 요청해요. 설명에는 그 키가 호출할 수 있는 것만 들어 있어요. 금액, 가격, 수량은 소수 문자열이에요.

</details>

데모 계정과 Bybit 개발자 보기의 읽기 전용 키 전송 예제 및 복구는 패널에 로그인한 사람만 사용할 수 있습니다. 액세스 키와 MCP는 `demoBybitView` 또는 `demo=1`을 사용할 수 없습니다.

## 다른 컴퓨터에서 <a href="#from-another-computer" id="from-another-computer"></a>

다른 컴퓨터의 프로그램이라면 거기서 커넥터를 `connect` 모드로 실행해요. 실행되는 동안 커넥터가 내 설치를 로컬 주소로 제공해요([페어링](https://docs.goodcrypto.app/goodcryptox-ko/goodcryptox-3.0/ai-agents.md#from-another-computer)). 그 컴퓨터에서 **Cursor 및 다른 앱** 옆의 **표시**를 누르고, 그 `env`의 값(`GCX_URL`과 `GCX_KEY`를 뺀 전부. 프로그램은 자기 키를 보내요)을 붙여 커넥터를 실행해요.

```sh
GCX_RELAY=… GCX_MAILBOX=… GCX_R=… GCX_PROFILE=… GCX_PAIR=… npx -y goodcryptox-connector@<version>-<build> connect --profile <the GCX_PROFILE value>
```

연결 주소가 출력되고, 이어서 `/api/v1`로 끝나는 API 주소가 출력돼요. 프로그램이 연결을 쓰는 동안은 계속 실행해 두고, 첫 번째 주소를 `GCX_URL`로 써요. 예를 들면 `http://127.0.0.1:8130`이에요.

<details>

<summary>다음 시작과 주소 변경</summary>

다음부터는 `npx -y goodcryptox-connector@<version>-<build> connect --profile <the profile>`을 실행해요. 저장된 페어링이 다시 쓰여요. 설치마다 프로필과 주소가 따로 있어요. 저장된 주소가 사용 중이면 `--choose-new-address`를 붙이고, 새 주소를 프로그램에 복사해요.

</details>

연결이 끊긴 동안 호출은 실패해요. 나중을 위해 저장되지 않아요. 우리 릴레이 없이 연결하려면 [SSH 터널](https://docs.goodcrypto.app/goodcryptox-ko/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead)을 써요.

goodcryptoX를 [홈 주소](https://docs.goodcrypto.app/goodcryptox-ko/goodcryptox-3.0/readme/set-up-on-your-mac.md#your-home-network)에서 열면 **API** 쪽의 **주소**가 그 주소예요. 같은 네트워크의 프로그램은 커넥터나 릴레이 없이 자기 키로 거기에 요청을 보내고, `/api/v1` 없는 주소를 `GCX_URL`로 써요. 믿을 수 있는 네트워크나 내 신뢰할 수 있는 HTTPS 주소를 쓰세요. HTTP에서는 트래픽을 읽을 수 있는 사람이 키를 복사할 수 있어요.

## 주문 보내기 <a href="#sending-an-order" id="sending-an-order"></a>

먼저 미리보기를 요청해요([주문 먼저 확인하기](https://docs.goodcrypto.app/goodcryptox-ko/goodcryptox-3.0/ai-agents.md#checking-an-order-first)). 그다음 다음 내용으로 `POST /api/v1/orders`를 보내요.

```json
{
  "requestId": "my-strategy-0001",
  "sourceId": "YOUR-ACCOUNT-ID",
  "instrumentId": "ETH",
  "type": "limit",
  "side": "buy",
  "size": "90",
  "sizeUnit": "quote",
  "price": "3000",
  "overrides": [],
  "bracket": {
    "reduceOnly": true,
    "tp": { "type": "market", "mode": "percent", "targets": [{ "value": "3", "share": "100" }] },
    "sl": { "type": "market", "mode": "percent", "value": "1.5" }
  }
}
```

계정의 레버리지를 아직 읽지 못했어도 무기한 선물 주문은 전송되고 거래소가 자체 레버리지를 적용해요. 이때 미리보기 내역에는 자금 정보가 없으며 마진은 확인되지 않았어요.

호가 통화로 수량을 정한 주문(`"sizeUnit": "quote"`, 코인 증거금 계약은 `"coin"`)은 그 금액을 유지해요. 코인 수량은 보낼 때마다 전송 가격으로 다시 계산해요(지정가는 가격을 바꿀 때마다 해당 지정가로, 스탑은 트리거 시). 주문 행에는 금액을 `cost` 및 `sizeUnit`로, 현재 코인 수량을 `size`로 함께 보여줘요. 거래소 최솟값 이상인 금액을 내림하면 최솟값보다 작아지는 경우 수량 한 단계만큼 올림해요. 따라서 행의 `size` 가치는 보낸 금액보다 최대 한 단계 더 클 수 있어요. 0보다 큰 수량이 이 올림 후에도 수량 한 단계보다 작아 아무것도 보내지 못하는 경우, 코인 수량 한 단계로 주문하고 응답에 이를 표시해요: `{"id": "o1", "size": "0.001", "sizeUnit": "base"}`. 수량 0은 거부돼요. 변경할 때는 `POST /api/v1/orders/{id}/modify`(MCP `modify_order`)에 `changes.sizeUnit`와 `size`를 함께 보내요. `{"size": "150", "sizeUnit": "quote"}`는 금액을 150으로 정하고, `{"price": "2900"}`는 새 가격에서 금액을 유지하며, `size`만 보내면 코인 수량이에요.

거래소 최소 주문 금액 미만의 주문도 보낸 그대로 전송돼요(미리보기에서 `trade.msgMinNotional`로 경고해요). 결과는 거래소의 응답이에요. 봇도 같아요. DCA 봇의 진입 및 평단가 조정 주문과 그리드의 최소 금액 미만 단계도 전송되고, 거래소가 거부한 주문은 봇의 실패한 주문이 돼요(DCA 단계 `failed`, 그리드의 `failed` 수). 다시 시도나 실패 복구로 다시 보내요. 봇 미리보기의 주문 요약 행은 이런 주문을 `under`로 표시해요. `sent` false는 너무 작아서 전송할 수 없는 주문에만 해당해요. `sendAll`이 있는 그리드 행은 모든 단계에 주문을 내고, 없는 행(이전 버전에서 실행)은 최소 금액 미만의 단계를 보류해요.

코인 마진 시장(`contract.method` `"DIV"`)에서 주문, 포지션, 봇의 수량은 계약 정보와 함께 계약 수로 제공돼요. USD = 계약 수 × `contract.multiplier`이고, 코인 = 해당 USD ÷ 가격이에요. `"sizingMode": "coin"`으로 수량을 정한 DCA 봇은 `entryAmount`와 `level1Amount`를 계약의 결제 코인(`contract.settlement`)으로 받아요. 각 주문은 해당 코인 수량을 자체 가격으로 계산한 뒤 정수 계약 수로 내림해요. `"cost"`는 주문마다 같은 USD 금액을 사용해요. USD 금액이 한 계약보다 작으면 한 계약의 USD 금액으로 시작하고, 각 단계는 그 금액을 기준으로 배율이 적용돼요.

헤지 모드 계정에서는 선물 시장에 `…:long`과 `…:short` 두 ID가 있으며 매수·매도 방향이 열기와 닫기를 결정해요. 롱에서 매도하거나 숏에서 매수하면 `reduceOnly` 여부와 관계없이 해당 포지션만 줄여요. 반대 방향의 `reduceOnly: true`는 거부돼요(`reduce-only-opens`).

보낸 뒤 응답이 오지 않아도 주문이 실패했다는 뜻은 아니에요. 다시 시도하기 전에 결과를 확인하세요. 거래 요청을 다시 보낼 때는 같은 `requestId`와 본문을 써야 같은 주문이 두 번 나가지 않아요.

`POST /api/v1/margin` Hyperliquid, Binance, Bybit에서 포지션의 격리 마진을 마진 코인으로 추가(양수 `amount`)하거나 뺍니다(음수)(MCP `change_margin`). Bybit EU는 현물만 지원해요. 거래 키는 레버리지를 설정할 때처럼 한도에 지정된 계정과 마켓에서 할 수 있어요. 한도가 없는 키나 다른 계정·마켓의 키는 422 `key.*`를 받고 아무것도 전송되지 않아요.

각 경로의 요청 본문과 거부 메시지는 `/api/v1/openapi.json`의 OpenAPI 문서에 있어요.

## 당신만 바꾸는 설정 <a href="#settings-only-you-change" id="settings-only-you-change"></a>

어떤 경로는 당신만 정하는 것을 바꿉니다. 키가 이를 호출하면 당신에게 전할 문장과 함께 403 `person-only`를 받고, 거래소에는 아무것도 보내지 않습니다. 에이전트가 무엇을 하면 되는지 알려 줄 수 있도록 MCP 도구가 있습니다.

* `POST /api/v1/accounts/{id}/bnb-fees` (`{"on": true}`) Binance 계정의 **BNB로 수수료 내기**를 켜거나 끕니다(MCP `set_bnb_fees`). `GET /api/v1/accounts`의 계정 행에 `bnbFees`로 표시됩니다: `on`, 그리고 그 뒤의 설정 `spot`과 `usdm`.

코인의 **담보** 스위치도 본인만 바꿀 수 있어요. `POST /api/v1/accounts/{id}/collateral`은 키에 403을 반환하고 MCP 도구는 없어요. 프로그램은 `balances` 토픽에서 설정을 읽어요(`perCoinCollateral`: 지갑과 각 코인의 `accepted`, `selected`, `fixed`; null은 알 수 없음이며 꺼짐이 아니에요). 또는 `GET /api/v1/accounts/{id}/collateral?coin=BTC`로 거래소에서 코인 하나를 바로 읽을 수 있어요(`{coin, accepted, selected}`; 읽기에 실패하거나 십 초가 넘게 걸리면 503).

계정 삭제는 본인만 할 수 있습니다. `POST /api/v1/accounts/{sourceId}/remove`는 Binance, Bybit, Bybit EU도 지원하며 계정 삭제용 MCP 도구는 제공되지 않습니다.

## 제안 철회하기 <a href="#withdrawing-a-proposal" id="withdrawing-a-proposal"></a>

주문이나 봇을 제안한 키는 내 결정을 기다리는 동안 그 제안을 철회할 수 있어요. `POST /api/v1/proposals/{id}/withdraw`에 `{"requestId": "..."}`를 붙여요. 범위는 **제안** 이상이에요. 응답은 `{"accepted": true}`이고, 다시 요청해도 같은 응답이에요. 다른 키의 제안은 없는 것처럼 404를 답해요. 내가 실행한 제안은 422 `proposal-launched`를, 내가 거절한 제안은 422 `proposal-rejected`를 답해요. 거절은 내 몫이고, 키는 거절할 수 없어요.

## 여러 계정의 목록 <a href="#lists-over-several-accounts" id="lists-over-several-accounts"></a>

`GET /api/v1/lists/positions`와 `GET /api/v1/lists/orders`는 목록에 포함된 모든 계정을 읽어요. 거래소에서 한 계정을 읽지 못해도 다른 계정은 숨겨지지 않아요. 읽은 계정이 하나라도 있으면 페이지의 `state`는 `live`로 유지되고, `accountStates`는 각 계정의 상태(`live`, `stale`, `unavailable` 또는 첫 조회를 기다리는 `waiting`)를 제공해 어느 계정의 행이 빠졌을 수 있는지 알 수 있어요. 페이지의 `state`는 읽을 수 있는 계정이 하나도 없을 때만 `stale` 또는 `unavailable`이 돼요. 모두 취소, 모두 정지, 모두 종료는 주문, 봇, 포지션마다 따로 응답해요. 실패한 항목은 해당 메시지와 함께 `refused`에 나열되고 나머지는 `count`와 `ids`에 집계돼요.

## 봇의 실패한 주문 <a href="#a-bots-failed-orders" id="a-bots-failed-orders"></a>

거절된 DCA 평단가 조정 주문이나 그리드 주문은 봇을 멈추지 않아서, 주의 행이나 봇의 `items`에 항목으로 올라가지 않아요. 거기에는 봇을 멈추게 하거나 네 확인을 기다리는 것만 있어요. DCA 봇의 실패한 평단가 조정 주문은 그 행의 `counters.averagingFailed`에서, 그리드는 `failed`(다음 섹션)에서 읽고, 실패한 주문마다는 그 주문 행에서 읽어요. `why`는 패널이 보여 주는 문장이고, `errorType`은 그 뒤에 있는 유형이고, `exchangeWords`는 거래소 자신의 말이에요. MCP 도구도 같은 행을 읽어요. `errorType`은 열린 문자열이에요. 아는 유형은 보여 주고 새 값도 받아들이세요. `exchangeWords`에는 거래소의 메시지 `text`와 있으면 `code`가 들어 있고, `reason`은 원래 응답을 그대로 가지고 있어요. 두 필드 모두 거래소의 거절이 없을 때와 이전 런타임에서는 없어요.

봇이 지금 다시 보낼 실패한 주문에는 `retry: true`가 붙어요. 그 주문에서 사람이 **다시 시도**를 누를 수 있다는 뜻이에요. 키는 이것을 보낼 수 없어서(`restore-level`은 키의 봇 명령에 없어요) 사람에게 알려 주세요. DCA 봇에서는 평단가 조정 주문이에요. `retry`가 없으면 봇이 그 주문을 거부해요. 일시 중지, 복구 중, 손절이 발동된 뒤, 익절이 따라가는 동안, 또는 그 단계의 이전 시도가 있을 때예요. 그리드에서는 실패한 주문의 가장 최근 시도의 주문 행이고, 그리드 행의 `orders`에 있는 실패한 주문의 줄에도 붙어요. 그 줄에는 `error`(우리 문장 `why`, 거래소가 거절했다면 `errorType`과 `exchangeWords`)와, 다시 놓으면 바로 체결될 동안에는 `past: true`가 있어요. `retry`가 없으면 그리드가 그 주문을 놓지 않아요. 일시 중지, 정지 중, 포지션이 거래소와 다름, 항목이 새 주문을 붙잡고 있음, 시도의 결과를 모름, 또는 다른 주문이 그 단계를 잡고 있을 때예요. 그리드 주문의 다시 시도는 그 주문 하나에 대한 **실패 복구**예요. 쓸 수 있는 잔액을 한 번 읽고, 응답은 그 주문에 대한 실패 복구의 `{"placed", "left", "needed", "unit"}`이에요.

## 봇이 계좌에 필요로 하는 것 <a href="#what-a-bot-needs-from-your-account" id="what-a-bot-needs-from-your-account"></a>

무기한 선물에서 봇 행의 `ownFunds`는 봇이 스탑(DCA는 손절)에 닿을 때까지, 스탑이 없으면 마지막 평단가 조정 주문이 체결될 때까지 계좌에서 필요한 자금이에요. 수수료를 포함하며, 사이클의 크기를 정할 때 미리보기의 `margin.survive`(`margin.toLast`)가 준 수치예요. 이전 버전의 DCA 사이클은 주문 가치 ÷ 레버리지를 그대로 유지해요. 그리드의 값은 행을 내려줄 때 계산하고, 끝난 그리드도 포함해요. `invested`(최대 계획)는 가장 큰 사이클의 계획이고, 아직 사이클이 없는 봇은 시작할 계획을 보여 줘요. 계좌의 퍼센트로 크기를 정한 봇은 필요한 금액이 그 퍼센트가 되도록 크기가 정해져요. 실행 중인 DCA는 다음 사이클부터, 그리드는 다음에 내는 주문부터예요.

## 그리드의 실패한 주문 <a href="#a-grids-failed-orders" id="a-grids-failed-orders"></a>

`GET /api/v1/bots`의 그리드 행에는 실패한 주문 수인 `failed`가 있어요. 0보다 크면 `failedWhy`도 있어요. 모두 자금 부족으로 거부되거나 취소됐으면 `money`, 그런 주문이 하나도 없으면 `other`, 나머지는 `mixed`예요. 주문 조회는 실패한 주문마다 상태를 함께 나열해요.

`POST /api/v1/bots/{id}/command`에 `{"requestId": "...", "kind": "fix-failed"}`를 보내면 패널의 **실패 복구** 버튼처럼 주문을 다시 놓아요. 새 주문에 쓸 수 있다고 거래소가 알려주는 자금을 새로 조회하고 전송 중인 내 주문만큼 뺀 뒤 현재가에 가까운 실패 주문부터 자금이 되는 만큼 놓아요. 조회한 자금이 감당하지 못하는 주문은 보내지 않아요. 응답은 `{"placed", "left", "needed", "unit"}`로, 보낸 수와 아직 실패한 수, 나머지에 추가로 필요한 `unit` 금액이에요(이후 거래소가 거부한 주문은 행의 `failed`에 다시 잡혀요). `later`는 다른 이유로 남긴 주문 수, `past`는 가격이 이미 지나가 즉시 보낸 주문 수예요. 일시 정지한 그리드는 422 `paused`로 응답하고 주문하지 않아요. 잔고 조회 실패 시 422 `balance`로 응답하고 주문하지 않으며 정지한 그리드는 409 `state`로 응답해요. 주문 작업이므로 키는 자신이 만든 그리드에 이 명령을 보낼 수 있어요. 봇 문제 목록에는 이제 `orders-failed` 항목이 없어요. 그 `facts.failed`는 더 이상 쓰이지 않아요(봇의 실패한 주문 참고). MCP 도구도 같은 작업에서 나와요.

시작 후 5분이 지나도 아직 정지 중이거나 시작 중이고, 네가 설정한 것을 기다리는 게 아닌 봇에는 원인이 `stuck-stopping`, `stuck-launching` 또는 `stuck-entry`(DCA 진입 미체결)인 항목이 붙어요. `GET /api/v1/bots/{id}`와 대시보드의 주의 행이 그것을 제공하고, 봇이 그 상태를 벗어나면 사라져요.

## $GOOD로 크레딧 결제하기 <a href="#paying-credits-with-good" id="paying-credits-with-good"></a>

크레딧은 본인의 지갑에서 결제해요. 프로그램이나 에이전트는 견적만 받을 수 있고 결제는 할 수 없어요. `POST /api/v1/credits/pay`에 `build: false`를 붙이면 결제로 무엇이 더해지는지 답해요([스키마](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-pay.schema.json)). 크레딧 추가와 같이 코인 수량으로 물어요. `input`은 그 코인 자체 단위의 수량이고, 경로 호출은 한 번이며, 결제는 정확히 그만큼을 써요. Solana에서는 $GOOD이 아닌 코인에 `burn: true`를 붙이면 같은 결제 안에서 $GOOD을 사서 소각하고, $GOOD 할인이 붙어요.

```json
{"chain":"solana","token":"native","input":"0.1007","burn":true,"payer":"<the wallet's address>","build":false}
```

응답의 `quote.credits`는 USD 크레딧이고, `quote.goodMore`는 같은 SOL로 $GOOD 없이 사는 것보다 얼마나 더 많은지예요(여기서는 약 9.90과 0.90). `token`에 $GOOD 민트 자체를 쓰면 보유한 $GOOD이 소각돼요(`burn`은 필요 없어요). `amount`(원하는 크레딧)와 `spend`($GOOD 경로에서 쓸 USD)도 계속 받아요.

Tron에서는 TRX가 결제 안에서 USDT로 스왑되고, 다른 TRC-20은 `no-route`로 응답해요.

응답에서 `quote.feeKept`는 결제가 수수료용으로 남기는 네트워크 고유 코인의 양이고, 그 코인 단위로 나와요(EVM 네트워크와 Tron).

## 크레딧 내역 합계 <a href="#credits-history-totals" id="credits-history-totals"></a>

결제 후에는 결제의 `{chain, id}`로(결제에 쓴 티커 `coin`도 함께 넣을 수 있고, 내역 항목에는 이것이 `paidWith`로 담겨요) `POST /api/v1/credits/pay/receipt`를 호출하면 우리 네트워크 어디서든 상태를 읽을 수 있어요. 크레딧은 보통 첫 확인 몇 초 뒤 `GET /api/v1/credits`에 나타나고, 네트워크가 나중에 취소한 결제는 `reason: "reversed"` 내역 행으로 회수돼요(음수 값이며, 그 `chain`과 `tx`, 그리고 `payment` 아래에 결제의 `token`, `amount`, `seq`가 있어요). 결제의 `token`은 도착한 코인(스왑 후에는 달러 토큰)이고 금액도 그 코인 단위예요. `paidWith`가 있으면 사람이 결제에 쓴 코인(TRX, ETH, SOL)이고 결제 표의 행에 이 코인이 나와요. 없으면(이 필드가 생기기 전의 결제나 앱 밖에서 보낸 결제) `token`을 쓰세요.

`GET /api/v1/credits`와 MCP `credits`는 같은 추가 선택 객체 `totals`를 반환해요([스키마](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-api.schema.json)). `totalPaid`, `paymentCredits`, `grants`, `totalVolume`, `totalFees`, `dailyVolume`, `dailyFees`, `monthlyVolume`, `monthlyFees`, `balanceDifference`는 USD 십진수 문자열이에요. `firstDay`는 첫 기록된 거래의 UTC 날짜 또는 null, `throughDay`는 오늘의 UTC 날짜이며 `dayCount`는 양 끝 날짜와 거래 없는 날을 모두 세요. 기록이 열흘뿐이거나 월이 바뀌어도 월평균은 일평균의 삼십 배예요. `paidEstimated`는 결제에서 추정한 비용을 나타내요. `balanceDifference = paymentCredits + grants - totalFees - balance`가 영이 아니면 경고하며 차단하지 않아요. 대기 중이거나 취소된 결제는 제외해요. 네트워크에서 취소된 결제는 그 `reversed` 행으로 `totalPaid`와 `paymentCredits`에서 빠지고, `grants`에는 절대 들어가지 않아요. 구버전에 합계가 없으면 확인된 날짜와 내역을 사용하고 수치가 일부 기록에 한정된다고 밝혀요. 기존 `days`와 `?before=YYYY-MM-DD` 페이지 조회는 그대로예요. 지갑 결제는 본인이 직접 해요. 수치가 완전할 때만 잔액 불일치를 경고해요. 모든 $GOOD 결제의 현금 비용은 추정치예요.

## 거래량 <a href="#trading-volume" id="trading-volume"></a>

읽기 권한으로 `GET /api/v1/trading-volume?before=YYYY-MM-DD`를 사용하거나 MCP 도구 `trading_volume`에 요청하세요. USD 기준 거래 금액, 체결 건수, 지불한 수수료와 실현 PnL을 계정별, 시장별, 주문을 낸 사람이나 키별로 보여 줘요. 각 계정을 goodcryptoX에 연결한 뒤의 거래가 대상이에요. [응답 스키마](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/trading-volume.schema.json)를 참고하세요.

`totals`는 저장된 모든 거래를 집계해요. `days`는 거래가 있는 최근 31일을 UTC 날짜 기준으로 최신순으로 보여 줘요. 다음 페이지를 받으려면 `next` 값을 `before`로 전달하세요. 해당 날짜는 다음 페이지에서 제외돼요. 금액은 USD 단위의 소수 문자열이에요. 펀딩비, 이체, 미체결 주문은 집계하지 않아요. 현물의 실현 PnL은 이 합계에 포함되지 않아요. 거래소 수수료와 goodcryptoX 수수료는 별도로 표시하며, 수수료 환급은 음수예요.

`manual`은 사람이나 액세스 키가 낸 주문을 뜻해요. `dca`와 `grid`는 봇 주문이에요. `gcx`는 goodcryptoX를 거친 주문인 것은 알지만, 어떤 종류의 주문이었는지 또는 누구의 키로 냈는지 더 이상 알 수 없다는 뜻이에요. `external`에는 goodcryptoX 밖에서 한 거래, 청산, 자동 디레버리징이 포함돼요.

각 계정의 합계를 완전한 것으로 보기 전에 `state`와 `reason`을 확인하세요. 계정을 연결하기 전의 거래는 집계하지 않아요. 내역을 남긴 채 제거했다가 되돌린 계정은 그동안 집계한 것을 유지하고, 되돌린 시점부터 다시 집계해요. `since`는 우리가 보관한 가장 오래된 거래의 시각을 밀리초로 나타내며, 그 이후의 모든 거래가 있다는 보장은 아니에요. 내역 읽기에 실패하면 재시도가 성공할 때까지 계정의 데이터는 불완전한 상태로 남아요. 새로 연결한 계정은 연결 이후의 거래를 읽는 동안 대기 상태예요. Binance에서는 goodcryptoX가 실행되는 동안 그 밖에서 한 거래도 집계해요. goodcryptoX가 꺼져 있을 때 한 거래나 비정상 종료로 사라진 거래는 빠질 수 있고, 특히 우리가 알지 못했던 시장에서 그럴 수 있어요.

`missing`은 USD로 다 평가하지 못한 거래 수예요. 거래소가 가격을 주지 않은 코인으로 낸 수수료나, 아직 몰랐던 마켓에서의 거래가 여기에 들어가요. 평가하지 못한 금액은 0으로 더하고, 아직 몰랐던 마켓에서의 거래는 그대로 남아요. `estimated`는 체결 시점의 가격 대신 보관 중이던 환율로 평가한 거래 수예요. 나중에 수치를 개선할 수 있도록 원래 금액을 보관해요. `unknownFees`는 주식 거래를 포함해 거래소 수수료를 알 수 없는 거래 수예요. `unknownPnl`은 무기한 선물 거래 중 실현 PnL이 영인 것으로 확인된 거래가 아니라, 실현 PnL을 알 수 없는 거래 수예요. 복구 필드는 저장된 내역을 어디까지 확인했는지 보여 줘요. 사용자에게 제공되는 `unmatchedFees`는 저장된 거래와 연결하지 못한 크레딧 차감 건수를 나타내요.

키는 읽기가 허용된 연결 계정만 볼 수 있어요. 자신의 `keyId`는 볼 수 있지만, 다른 키와 사용자의 수치는 식별자 없이 합쳐져요. 데모 수치와 지워진 계정은 제외돼요. 존재하지 않는 날짜는 400을 반환해요.

## 포트폴리오 식별 <a href="#portfolio-identities" id="portfolio-identities"></a>

`GET /api/v1/portfolio`와 읽기 전용 MCP 도구 `portfolio`는 기존의 계정 보충 정보, 스냅샷, 손익 옆에 `assets`를 더해요. 각 자산에는 `assetId`, `assetKind`(`bundled` 또는 `exchange`), `symbol`, `name`, `amount`, `value`, `unpriced`, `holdings`가 있어요. `bundled`는 지금은 한 계정에만 있어도 레지스트리의 명시적인 식별을 뜻해요. `exchange`는 짝이 없는 거래소 자산이고, id에 거래소와 정확한 자산 코드가 들어가요. 행을 `symbol`로 묶지 마세요.

`holdings`는 각 계정, 거래소, 원래 코드, 수량, 가격, 가치, 가격 없음 표시를 그대로 가져요. 가치와 가격은 USD 십진수 문자열이에요. 수량은 그 보유분의 단위이고, 가치만 있는 지갑 금액은 null이에요. 그룹의 가치는 보유분의 가치를 합한 값이에요. 한 거래소의 2 UBTC(60,000)와 다른 거래소의 1 BTC(61,000)는 181,000이지, 기준 가격의 세 배가 아니에요. 가격이 없으면 수량은 남고 가치는 0으로 더해져요. 구성 요소 중 하나라도 가격이 없으면 `unpriced`는 true예요. 가격은 로컬 런타임이 아는 가장 최근 값이고, 이 조회는 가격을 만들어 내지 않으며 goodcryptoX 서비스도 필요하지 않아요. 잔액에서 제외한 계정과 데모 자금은 연결된 자산 합계에 없어요. 이전 런타임은 `assets`를 생략하고, 기존 필드의 의미는 모두 그대로예요.

응답의 `pnl`은 계정이 goodcryptoX에 연결된 뒤 낸 손익으로, goodcryptoX 자체 기록을 바탕으로 모든 거래소에서 똑같이 계산해요. 수수료를 뺀 청산된 선물 거래와 펀딩이에요. `accounts`의 각 행에는 그 계정의 PnL을 세기 시작하는 시점인 `connected`가 있고, 그 이전은 어떤 기간에도 들어가지 않아요.

포지션 수치는 `positions` 토픽(MCP의 `snapshot`)으로 읽으세요. `GET /api/v1/funding?sourceId=&instrumentId=`와 읽기 전용 MCP 도구 `funding`은 부호가 있는 지급액과 각 봇의 몫을 반환합니다. 선택 항목 `id`는 거래소 지급 건을 식별하며, `asset`은 기존 `usdc` 필드 금액에 대해 거래소가 명시한 코인입니다. 금액이 USDC라고 가정하지 마세요. Binance 헤지 모드 지급액은 거래소가 방향을 제공하지 않아 계정에 남습니다. 호환성: 이전 행에는 `id`와 `asset`이 없으며 기존 필드의 의미는 유지됩니다.

## 자주 묻는 질문 <a href="#questions" id="questions"></a>

### OpenAPI 문서가 있나요? <a href="#is-there-an-openapi-document" id="is-there-an-openapi-document"></a>

네. 내 설치 주소의 `/api/v1/openapi.json`에 있고, 같은 Bearer 헤더로 요청해요. 그 키가 호출할 수 있는 것만 설명해요.

### API를 다른 컴퓨터에서도 쓸 수 있나요? <a href="#does-the-api-work-from-another-computer" id="does-the-api-work-from-another-computer"></a>

네. 거기서 커넥터를 `connect` 모드로 실행하면, 실행되는 동안 내 설치를 로컬 주소로 제공해요. [SSH 터널](https://docs.goodcrypto.app/goodcryptox-ko/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead)도 돼요.

### 프로그램이 주문을 낼 수 있나요? <a href="#can-a-program-place-orders" id="can-a-program-place-orders"></a>

네. **거래** 키라면 `POST /api/v1/orders`로, 그 키의 계정, 시장, 한도 안에서 낼 수 있어요. 먼저 미리보기를 요청하세요. 미리보기는 아무것도 보내지 않아요.

### 요청이 시간 초과되면 어떻게 되나요? <a href="#what-happens-if-my-request-times-out" id="what-happens-if-my-request-times-out"></a>

응답이 오지 않아도 주문이 실패했다는 뜻은 아니에요. 다시 시도하기 전에 결과를 확인하세요. 다시 보낼 때는 같은 `requestId`와 본문을 써야 같은 주문이 두 번 나가지 않아요.
