> 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-vi/goodcryptox-3.0/api.md).

# API

Đọc và giao dịch qua API cục bộ của goodcryptoX từ chương trình của chính bạn, với cùng khóa và giới hạn như một tác tử AI.

Chương trình của chính bạn đọc và giao dịch trên các sàn bạn kết nối qua API của goodcryptoX, được mô tả trong tài liệu OpenAPI của nó. Một chương trình dùng cùng khóa, quyền và giới hạn như một tác tử AI ([Khóa và giới hạn](https://docs.goodcrypto.app/goodcryptox-vi/goodcryptox-3.0/ai-agents.md#keys-and-limits)).

`POST /api/v1/accounts/{id}/check` (MCP `check_api_key`) đọc lại quyền của khóa API cho tài khoản Binance, Bybit hoặc Bybit EU, giống như **Kiểm tra lại** trên thẻ tài khoản.

Mỗi con số đến bằng tiền tệ của giao dịch đó: giá và giá trị bằng tiền định giá của thị trường, PnL bằng tài sản mà dòng của nó ghi, tín dụng và `GET /api/v1/portfolio` bằng USD, giới hạn của khóa bằng tiền tệ lúc đặt. `GET /api/v1/rates` trả về tiền tệ cơ bản của bạn và tỷ giá cho mỗi 1 USD, để hiển thị con số như goodcryptoX.

Công cụ MCP `instruments` và `GET /api/v1/instruments?venue=…` bao gồm khối lượng đã biết trong 24 giờ của mỗi thị trường (giá trị bằng tiền định giá), biến động giá (phần trăm) và giá giao dịch gần nhất nếu sàn gửi giá này. API cũng cung cấp `instrument-stats/<venue>` qua [đường dẫn chủ đề](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/runtime/api.md#the-socket). Các con số này vẫn là chuỗi thập phân. Với khối lượng và biến động giá, null giữ lại giá trị đã biết trước đó; trường tùy chọn `invalidate` chỉ ra các giá trị cần xóa. Nếu thiếu `lastPrice`, giá trước đó được giữ lại để đảm bảo tương thích; nếu gửi rõ null thì giá đó bị xóa.

Trong **Thiết lập › MCP & API**, tạo một khóa ([cách làm](https://docs.goodcrypto.app/goodcryptox-vi/goodcryptox-3.0/ai-agents.md#connect-any-mcp-app-or-program)); phía **API** của khối kết nối khi đó có ba dòng, mỗi dòng có biểu tượng sao chép: **Địa chỉ**, **Khóa**, và tiêu đề mà chương trình của bạn gửi kèm mọi yêu cầu, có khóa đã chọn bên trong: `Authorization: Bearer <your key>`. Biểu tượng sao chép cạnh tiêu đề sao chép nguyên cả dòng.

<details>

<summary>Ví dụ yêu cầu API</summary>

Đặt `GCX_URL` thành origin mà chương trình của bạn truy cập được và cung cấp `GCX_KEY` trong môi trường của nó. Ví dụ này đọc các tài khoản:

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

Tài liệu OpenAPI nằm ở `$GCX_URL/api/v1/openapi.json`. Chương trình yêu cầu tài liệu bằng cùng tiêu đề Bearer; phần mô tả chỉ gồm những gì khóa của nó được gọi. Số tiền, giá và khối lượng là chuỗi số thập phân.

</details>

Tài khoản demo và chế độ Bybit dành cho nhà phát triển, gồm ví dụ gửi bằng khóa chỉ đọc và khôi phục, dành cho người đã đăng nhập bảng điều khiển. Khóa truy cập và MCP không thể dùng `demoBybitView` hoặc `demo=1`.

## Từ máy tính khác <a href="#from-another-computer" id="from-another-computer"></a>

Với chương trình trên máy tính khác, hãy chạy trình kết nối ở đó ở chế độ `connect`: khi nó chạy, nó phục vụ bản cài của bạn ở một địa chỉ cục bộ ([ghép nối](https://docs.goodcrypto.app/goodcryptox-vi/goodcryptox-3.0/ai-agents.md#from-another-computer)). Bấm **Hiện** cạnh **Cursor và ứng dụng khác** trên máy tính đó và chạy trình kết nối với các giá trị của `env` của nó (tất cả trừ `GCX_URL` và `GCX_KEY`; chương trình của bạn gửi khóa riêng của nó):

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

Nó in ra địa chỉ kết nối, rồi địa chỉ API kết thúc bằng `/api/v1`. Giữ nó chạy trong lúc chương trình của bạn dùng kết nối, và dùng địa chỉ đầu tiên làm `GCX_URL`, ví dụ `http://127.0.0.1:8130`.

<details>

<summary>Các lần khởi động sau và thay đổi địa chỉ</summary>

Ở các lần khởi động sau, chạy `npx -y goodcryptox-connector@<version>-<build> connect --profile <the profile>`; ghép nối đã lưu được dùng lại. Mỗi bản cài có hồ sơ và địa chỉ riêng. Nếu địa chỉ đã lưu của nó đang được dùng, thêm `--choose-new-address`, rồi sao chép địa chỉ mới vào chương trình của bạn.

</details>

Khi bị ngắt kết nối, các lệnh gọi thất bại; chúng không được lưu lại để dùng sau. Để kết nối mà không qua relay của chúng tôi, hãy dùng [đường hầm SSH](https://docs.goodcrypto.app/goodcryptox-vi/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead).

Khi bạn mở goodcryptoX ở [địa chỉ ở nhà](https://docs.goodcrypto.app/goodcryptox-vi/goodcryptox-3.0/readme/set-up-on-your-mac.md#your-home-network), **Địa chỉ** ở phía **API** chính là địa chỉ đó: một chương trình trong cùng mạng gửi yêu cầu đến đó bằng khóa của nó, không qua trình kết nối hay relay của chúng tôi, và dùng địa chỉ không có `/api/v1` làm `GCX_URL`. Dùng trên mạng tin cậy hoặc địa chỉ HTTPS riêng đáng tin: qua HTTP, người đọc được lưu lượng có thể sao chép khóa.

## Gửi một lệnh <a href="#sending-an-order" id="sending-an-order"></a>

Hãy yêu cầu xem trước trước ([Kiểm tra lệnh trước](https://docs.goodcrypto.app/goodcryptox-vi/goodcryptox-3.0/ai-agents.md#checking-an-order-first)). Sau đó `POST /api/v1/orders` với:

```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" }
  }
}
```

Khi chưa đọc được đòn bẩy của tài khoản, lệnh hợp đồng vĩnh cửu vẫn được gửi và sàn áp dụng đòn bẩy của mình; lúc đó biên nhận xem trước không có dữ liệu về tiền và ký quỹ chưa được kiểm tra.

Lệnh có khối lượng theo đồng tiền định giá (`"sizeUnit": "quote"`, hoặc `"coin"` trên hợp đồng ký quỹ bằng coin) giữ nguyên giá trị đó: số coin được tính lại mỗi lần gửi, theo giá gửi (lệnh giới hạn theo giá của nó sau mỗi lần đổi giá; stop khi kích hoạt). Dòng lệnh hiện giá trị dưới dạng `cost` và `sizeUnit` bên cạnh `size`, số coin hiện tại. Giá trị bằng hoặc cao hơn mức tối thiểu của sàn được làm tròn lên một bước khối lượng nếu làm tròn xuống sẽ thấp hơn mức tối thiểu, nên `size` trên dòng có thể có giá trị lớn hơn số đã gửi tối đa một bước. Khối lượng lớn hơn không nhưng sẽ không gửi được gì (dưới một bước khối lượng sau lần làm tròn đó) được đặt bằng một bước của coin, và phản hồi sẽ nêu rõ: `{"id": "o1", "size": "0.001", "sizeUnit": "base"}`; khối lượng bằng không bị từ chối. Để thay đổi, `POST /api/v1/orders/{id}/modify` (MCP `modify_order`) nhận `changes.sizeUnit` cùng `size`: `{"size": "150", "sizeUnit": "quote"}` đặt giá trị thành 150, `{"price": "2900"}` giữ nguyên giá trị ở giá mới, còn chỉ `size` là số coin.

Lệnh dưới giá trị lệnh tối thiểu của sàn được gửi đúng như bạn gửi (bản xem trước cảnh báo bằng `trade.msgMinNotional`); kết quả là câu trả lời của sàn. Bot cũng vậy: lệnh vào và lệnh trung bình giá của bot DCA cùng các mức Grid dưới mức tối thiểu vẫn được gửi; lệnh bị sàn từ chối trở thành lệnh thất bại của bot (mức DCA `failed`, số đếm `failed` của Grid), được gửi lại bằng Thử lại hoặc Đặt lại lệnh lỗi. Hàng tóm tắt trong bản xem trước bot đánh dấu lệnh đó là `under`; `sent` false chỉ dành cho lệnh quá nhỏ để gửi. Hàng Grid có `sendAll` đặt mọi mức; hàng không có nó (khởi chạy bằng phiên bản cũ) giữ lại các mức dưới mức tối thiểu.

Trên thị trường ký quỹ bằng coin (`contract.method` `"DIV"`), khối lượng lệnh, vị thế và bot được trả về theo hợp đồng cùng thông số hợp đồng: USD = hợp đồng × `contract.multiplier`, và coin = số USD đó ÷ giá. Bot DCA với `"sizingMode": "coin"` nhận `entryAmount` và `level1Amount` bằng đồng tiền thanh toán của hợp đồng (`contract.settlement`): mỗi lệnh là lượng coin đó theo giá riêng của lệnh, làm tròn xuống số hợp đồng nguyên. `"cost"` dùng cùng số USD cho mỗi lệnh; số USD nhỏ hơn một hợp đồng bắt đầu từ giá trị USD của một hợp đồng, và mỗi mức được nhân theo hệ số từ đó.

Trên tài khoản ở Chế độ phòng hộ, thị trường futures có hai ID, `…:long` và `…:short`, và phía lệnh quyết định mở hoặc đóng: bán trên long hoặc mua trên short chỉ giảm vị thế đó, có hoặc không có `reduceOnly`; `reduceOnly: true` ở phía còn lại bị từ chối (`reduce-only-opens`).

Mất phản hồi sau khi gửi không có nghĩa là lệnh đã thất bại: hãy kiểm tra kết quả trước khi thử lại. Khi thử lại một yêu cầu giao dịch, hãy giữ nguyên `requestId` và nội dung để nó không thể đặt cùng một lệnh hai lần.

`POST /api/v1/margin` thêm (`amount` dương) hoặc rút (âm) ký quỹ cô lập của một vị thế trên Hyperliquid, Binance và Bybit, bằng đồng ký quỹ của nó (MCP `change_margin`). Bybit EU chỉ hỗ trợ spot. Khóa Giao dịch làm được việc này trên các tài khoản và thị trường mà hạn mức của nó nêu, như khi đặt đòn bẩy: khóa không có hạn mức, hoặc dành cho tài khoản hay thị trường khác, nhận 422 `key.*` và không có gì được gửi.

Nội dung yêu cầu và các thông báo từ chối của mọi tuyến nằm trong tài liệu OpenAPI ở `/api/v1/openapi.json`.

## Cài đặt chỉ bạn thay đổi <a href="#settings-only-you-change" id="settings-only-you-change"></a>

Một số route thay đổi điều chỉ bạn quyết định: khóa gọi chúng nhận 403 `person-only` kèm một câu để chuyển cho bạn, và không có gì được gửi tới sàn. Các công cụ MCP của chúng tồn tại để agent có thể nói cho bạn biết cần làm gì.

* `POST /api/v1/accounts/{id}/bnb-fees` (`{"on": true}`) bật hoặc tắt **Trả phí bằng BNB** cho một tài khoản Binance (MCP `set_bnb_fees`). Dòng của tài khoản trong `GET /api/v1/accounts` hiển thị nó là `bnbFees`: `on`, và các cài đặt phía sau, `spot` và `usdm`.

Công tắc **Thế chấp** của coin cũng chỉ dành cho bạn: `POST /api/v1/accounts/{id}/collateral` trả về 403 cho khóa và không có công cụ MCP. Chương trình đọc cài đặt trong chủ đề `balances` (`perCoinCollateral`: ví, cùng `accepted`, `selected` và `fixed` cho từng coin; null là không rõ, không bao giờ là Tắt), hoặc đọc một coin từ sàn ngay lúc đó bằng `GET /api/v1/accounts/{id}/collateral?coin=BTC` (`{coin, accepted, selected}`; 503 khi đọc thất bại hoặc mất hơn mười giây).

Chỉ bạn mới có thể xóa tài khoản: `POST /api/v1/accounts/{sourceId}/remove` cũng hỗ trợ Binance, Bybit và Bybit EU; không có công cụ MCP để xóa tài khoản.

## Rút lại một đề xuất <a href="#withdrawing-a-proposal" id="withdrawing-a-proposal"></a>

Một khóa đã đề xuất lệnh hoặc bot có thể rút nó lại trong lúc nó chờ bạn: `POST /api/v1/proposals/{id}/withdraw` với `{"requestId": "..."}`, phạm vi **Đề xuất** trở lên. Câu trả lời là `{"accepted": true}`; hỏi lại thì được câu trả lời giống hệt. Đề xuất của khóa khác trả lời 404, như thể nó không tồn tại; đề xuất bạn đã khởi chạy trả lời 422 `proposal-launched`, và đề xuất bạn đã từ chối trả lời 422 `proposal-rejected`. Việc từ chối vẫn là của bạn: một khóa không thể từ chối.

## Danh sách trên nhiều tài khoản <a href="#lists-over-several-accounts" id="lists-over-several-accounts"></a>

`GET /api/v1/lists/positions` và `GET /api/v1/lists/orders` đọc mọi tài khoản thuộc danh sách. Một tài khoản không đọc được từ sàn không làm ẩn các tài khoản khác: `state` của trang vẫn là `live` khi có ít nhất một tài khoản đã đọc được, và `accountStates` cho biết trạng thái của từng tài khoản (`live`, `stale`, `unavailable` hoặc `waiting` ở lần đọc đầu), để bạn biết có thể thiếu hàng của tài khoản nào. `state` của trang chỉ là `stale` hoặc `unavailable` khi không đọc được tài khoản nào. Hủy tất cả, Dừng tất cả và Đóng tất cả trả lời riêng cho từng lệnh, bot hoặc vị thế: mục thất bại được liệt kê trong `refused` cùng thông báo của nó, các mục còn lại được tính trong `count` và `ids`.

## Các lệnh thất bại của bot <a href="#a-bots-failed-orders" id="a-bots-failed-orders"></a>

Lệnh trung bình giá của DCA hoặc lệnh của grid bị từ chối không làm bot dừng, nên không nằm trong các hàng cần chú ý hay trong `items` của bot; ở đó chỉ có những gì làm bot dừng hoặc chờ bạn. Đọc các lệnh trung bình giá thất bại của bot DCA ở `counters.averagingFailed` trên hàng của nó, của grid ở `failed` (phần kế tiếp), và từng lệnh thất bại ở hàng lệnh của nó: `why` là câu mà bảng điều khiển hiển thị, `errorType` là loại đứng sau câu đó và `exchangeWords` là lời của chính sàn; các công cụ MCP đọc cùng các hàng này. `errorType` là chuỗi mở: hiển thị các loại bạn biết và chấp nhận giá trị mới. `exchangeWords` chứa thông báo `text` của sàn và `code` tùy chọn; `reason` giữ phản hồi gốc. Cả hai trường đều không có khi không có sàn từ chối và trên các bản cũ hơn.

Lệnh thất bại của bot mà bot sẽ gửi lại bây giờ mang `retry: true`: người dùng có thể bấm **Thử lại** ở lệnh đó. Một khóa không thể gửi nó (`restore-level` không nằm trong các lệnh bot của khóa), nên hãy báo cho người dùng. Ở bot DCA đó là lệnh trung bình giá; không có `retry` thì bot sẽ từ chối nó: đang tạm dừng, đang sửa, sau khi cắt lỗ đã chạy, khi chốt lời đang theo, hoặc là lần thử trước của mức đó. Ở grid đó là hàng lệnh của lần thử mới nhất của lệnh thất bại, và dòng của lệnh thất bại trong `orders` của hàng grid cũng mang nó, cùng `error` (câu `why` của chúng ta, cùng `errorType` và `exchangeWords` khi sàn từ chối) và `past: true` khi đặt lại sẽ khớp ngay. Không có `retry` thì grid sẽ không đặt nó: đang tạm dừng, đang dừng, vị thế của nó khác với của sàn, một mục đang giữ các lệnh mới của nó, kết quả lần thử không rõ, hoặc một lệnh khác đang giữ mức đó. Thử lại ở lệnh của grid là **Đặt lại lệnh lỗi** cho riêng lệnh đó: một lần đọc phần còn trống, và câu trả lời là `{"placed", "left", "needed", "unit"}` của Đặt lại lệnh lỗi cho lệnh đó.

## Bot cần gì từ tài khoản của bạn <a href="#what-a-bot-needs-from-your-account" id="what-a-bot-needs-from-your-account"></a>

Trên hợp đồng vĩnh cửu, `ownFunds` ở hàng của bot là số tiền bot cần từ tài khoản của bạn để chạm điểm dừng (cắt lỗ của DCA), hoặc để khớp lệnh trung bình giá cuối cùng khi không có điểm dừng, đã gồm phí: con số mà `margin.survive` (`margin.toLast`) của bản xem trước đã đưa ra khi chu kỳ được đặt khối lượng. Chu kỳ DCA từ phiên bản cũ giữ giá trị các lệnh ÷ đòn bẩy của nó. Với Grid, nó được tính khi hàng được phục vụ, kể cả grid đã kết thúc. `invested` (Tối đa dự kiến) là kế hoạch của chu kỳ lớn nhất; bot chưa có chu kỳ hiện kế hoạch mà nó sẽ bắt đầu. Bot đặt khối lượng theo phần trăm tài khoản được đặt sao cho nhu cầu của nó bằng phần trăm đó: DCA đang chạy từ chu kỳ kế tiếp, Grid từ lệnh kế tiếp nó đặt.

## Các lệnh thất bại của grid <a href="#a-grids-failed-orders" id="a-grids-failed-orders"></a>

Dòng grid trong `GET /api/v1/bots` có `failed`, số lệnh thất bại, và khi số đó lớn hơn không, có thêm `failedWhy`: `money` nếu tất cả bị từ chối hoặc hủy vì thiếu tiền, `other` nếu không lệnh nào như vậy, và `mixed` trong các trường hợp còn lại. Truy vấn lệnh liệt kê từng lệnh thất bại cùng trạng thái.

`POST /api/v1/bots/{id}/command` với `{"requestId": "...", "kind": "fix-failed"}` đặt lại chúng, giống **Đặt lại lệnh lỗi** trong bảng điều khiển: đọc lại số tiền sàn cho biết còn trống cho một lệnh mới, trừ các lệnh đang gửi của bạn, rồi đặt các lệnh thất bại gần giá nhất trước, trong phạm vi số tiền đó. Không gửi gì vượt quá số tiền lần đọc xác nhận. Phản hồi là `{"placed", "left", "needed", "unit"}`: số đã gửi, số còn thất bại và lượng `unit` cần thêm cho phần còn lại (lệnh sau đó bị sàn từ chối sẽ xuất hiện lại trong `failed` của dòng); `later` đếm các lệnh để lại vì lý do khác, `past` đếm các lệnh gửi ngay vì giá đã đi qua. Grid tạm dừng trả về 422 `paused` và không đặt gì; đọc số dư thất bại trả về 422 `balance` và không đặt gì; grid đã dừng trả về 409 `state`. Đây là thao tác lệnh, nên khóa có thể gửi cho grid do chính nó tạo. Các mục vấn đề của bot không còn mục `orders-failed`; `facts.failed` của nó đã lỗi thời (xem Các lệnh thất bại của bot). Công cụ MCP dùng cùng thao tác.

Bot vẫn đang dừng hoặc khởi chạy sau năm phút kể từ khi bắt đầu, mà không chờ điều gì bạn đặt, sẽ mang một mục có nguyên nhân `stuck-stopping`, `stuck-launching` hoặc `stuck-entry` (lệnh vào DCA chưa khớp); `GET /api/v1/bots/{id}` và các hàng cần chú ý trên Dashboard trả về mục này, và nó biến mất khi bot rời trạng thái đó.

## Trả tín dụng bằng $GOOD <a href="#paying-credits-with-good" id="paying-credits-with-good"></a>

Tín dụng được trả từ ví của chính người dùng; chương trình hay tác nhân chỉ có thể báo giá, không bao giờ trả. `POST /api/v1/credits/pay` với `build: false` trả lời một khoản thanh toán sẽ cộng bao nhiêu ([lược đồ](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-pay.schema.json)). Hỏi theo số lượng coin, như Thêm tín dụng làm: `input` là số lượng theo đơn vị của chính coin, một lần gọi tuyến, và khoản thanh toán chi đúng số đó. Trên Solana, `burn: true` với bất kỳ coin nào trừ $GOOD sẽ mua $GOOD trong cùng khoản thanh toán rồi đốt nó, để có mức giảm của $GOOD:

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

`quote.credits` trong câu trả lời là số tín dụng tính bằng USD và `quote.goodMore` là phần nhiều hơn so với cùng số SOL mua được khi không dùng $GOOD (ở đây khoảng 9,90 và 0,90). Khi `token` là chính mint của $GOOD, số $GOOD đang có sẽ bị đốt (không cần `burn`). `amount` (số tín dụng muốn có) và `spend` (số USD chi trên các đường dùng $GOOD) vẫn được chấp nhận.

Trên Tron, TRX được đổi sang USDT trong khoản thanh toán; mọi TRC-20 khác đều nhận `no-route`.

Trong câu trả lời, `quote.feeKept` là lượng coin gốc của mạng mà khoản thanh toán để lại cho phí, tính bằng chính coin đó (mạng EVM và Tron).

## Tổng số liệu lịch sử tín dụng <a href="#credits-history-totals" id="credits-history-totals"></a>

Sau khi người dùng thanh toán, `POST /api/v1/credits/pay/receipt` với `{chain, id}` của thanh toán (và `coin`, mã coin đã dùng để trả, mà mục lịch sử của thanh toán sau đó mang dưới tên `paidWith`) sẽ đọc trạng thái của nó trên bất kỳ mạng nào của chúng tôi; tín dụng thường hiện trong `GET /api/v1/credits` vài giây sau lần xác nhận đầu tiên, và thanh toán bị mạng loại bỏ về sau sẽ bị thu hồi bằng một dòng lịch sử có `reason: "reversed"` (âm, ghi `chain` và `tx` của nó, cùng `token`, `amount` và `seq` của thanh toán trong `payment`). `token` của một thanh toán là coin đã đến (sau hoán đổi là token đô la) và các con số của nó tính bằng coin đó; `paidWith`, khi có, là coin người dùng đã trả (TRX, ETH, SOL), được dòng trong Thanh toán ghi; khi không có (thanh toán có trước trường này, hoặc gửi từ ngoài ứng dụng), hãy ghi `token`.

`GET /api/v1/credits` và MCP `credits` trả về cùng đối tượng bổ sung tùy chọn `totals` ([lược đồ](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-api.schema.json)). `totalPaid`, `paymentCredits`, `grants`, `totalVolume`, `totalFees`, `dailyVolume`, `dailyFees`, `monthlyVolume`, `monthlyFees` và `balanceDifference` là chuỗi thập phân bằng USD. `firstDay` là ngày UTC của giao dịch đầu tiên được ghi nhận hoặc null, `throughDay` là ngày UTC hôm nay, còn `dayCount` tính cả hai đầu và ngày không giao dịch. Trung bình tháng bằng ba mươi lần trung bình ngày, kể cả khi chỉ có mười ngày lịch sử hoặc qua ranh giới tháng. `paidEstimated` đánh dấu chi phí suy ra của thanh toán. `balanceDifference = paymentCredits + grants - totalFees - balance`; giá trị khác không tạo cảnh báo, không bao giờ chặn. Thanh toán đang chờ và đã hoàn tác bị loại trừ; thanh toán bị mạng loại bỏ được trừ khỏi `totalPaid` và `paymentCredits` bằng dòng `reversed` của nó, không bao giờ tính vào `grants`. Nếu phiên bản cũ thiếu tổng số liệu, dùng các ngày và lịch sử đã biết, đồng thời nêu rõ số liệu chưa đầy đủ. `days` và phân trang `?before=YYYY-MM-DD` không đổi. Thanh toán từ ví vẫn do chính người dùng thực hiện. Chỉ khi số liệu đầy đủ mới có thể cảnh báo số dư không khớp. Chi phí bằng tiền của mọi thanh toán $GOOD đều là ước tính.

## Khối lượng giao dịch <a href="#trading-volume" id="trading-volume"></a>

Dùng `GET /api/v1/trading-volume?before=YYYY-MM-DD` với quyền đọc, hoặc hỏi công cụ MCP `trading_volume`. Công cụ cho biết giá trị bạn đã giao dịch bằng USD, số giao dịch đã khớp, phí đã trả và PnL đã chốt, theo tài khoản, thị trường và người đặt lệnh, kể từ khi bạn kết nối từng tài khoản với goodcryptoX. Xem [cấu trúc phản hồi](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/trading-volume.schema.json).

`totals` bao gồm tất cả giao dịch chúng tôi đã lưu. `days` hiển thị 31 ngày UTC gần nhất có giao dịch, từ mới đến cũ. Để lấy trang tiếp theo, truyền `next` vào `before`; ngày đó sẽ không có trong trang tiếp theo. Các số tiền là chuỗi thập phân bằng USD. Funding, chuyển tiền và lệnh chưa khớp không được tính. PnL đã chốt trên spot không nằm trong các tổng này. Phí sàn và phí goodcryptoX được tách riêng; khoản hoàn phí mang giá trị âm.

`manual` nghĩa là lệnh do một người hoặc khóa truy cập đặt. `dca` và `grid` là lệnh của bot. `gcx` nghĩa là chúng tôi biết lệnh được gửi qua goodcryptoX, nhưng không còn biết đó là loại lệnh nào hoặc khóa của ai đã đặt lệnh. `external` bao gồm giao dịch ngoài goodcryptoX, thanh lý và tự động giảm đòn bẩy.

Kiểm tra `state` và `reason` của từng tài khoản trước khi coi các tổng của tài khoản đó là đầy đủ. Giao dịch từ trước khi bạn kết nối một tài khoản không được tính. Tài khoản bạn đã gỡ nhưng giữ lịch sử rồi thêm lại sẽ giữ những gì đã tính và tính tiếp từ lúc thêm lại. `since` là thời điểm của giao dịch cũ nhất mà chúng tôi còn giữ, tính bằng mili giây; không đảm bảo rằng mọi giao dịch sau đó đều có mặt. Nếu đọc lịch sử thất bại, dữ liệu tài khoản vẫn chưa đầy đủ cho đến khi thử lại thành công. Tài khoản mới kết nối vẫn ở trạng thái chờ trong khi chúng tôi đọc các giao dịch kể từ lúc kết nối. Trên Binance, chúng tôi tính các giao dịch ngoài goodcryptoX trong lúc goodcryptoX đang chạy. Có thể thiếu giao dịch thực hiện khi goodcryptoX tắt hoặc bị mất khi chương trình gặp sự cố, nhất là trên những thị trường chúng tôi chưa biết đến.

`missing` đếm các giao dịch chúng tôi chưa thể định giá đầy đủ bằng USD: phí trả bằng một coin mà sàn không cho chúng tôi giá, hoặc giao dịch trên một thị trường chúng tôi chưa biết. Phần không định giá được tính bằng không; giao dịch trên thị trường chúng tôi chưa biết sẽ giữ nguyên như vậy. `estimated` đếm các giao dịch được định giá bằng tỷ giá đã lưu thay vì giá tại thời điểm khớp. Chúng tôi giữ nguyên số tiền gốc để có thể cải thiện các số liệu này sau. `unknownFees` đếm các giao dịch chưa biết phí sàn, kể cả giao dịch cổ phiếu. `unknownPnl` đếm các giao dịch hợp đồng vĩnh cửu có PnL đã chốt chưa xác định, thay vì đã biết là bằng không. Các trường khôi phục cho biết chúng tôi đã kiểm tra đến đâu trong lịch sử đã lưu. Với người dùng, `unmatchedFees` đếm các khoản trừ tín dụng mà chúng tôi không thể liên kết với giao dịch đã lưu.

Một khóa chỉ thấy các tài khoản đã kết nối mà khóa được phép đọc. Khóa thấy `keyId` của chính mình; số liệu của các khóa khác và người dùng được gộp lại mà không kèm mã định danh của họ. Số liệu demo và tài khoản đã xóa không được tính. Ngày không tồn tại trả về 400.

## Nhận diện tài sản trong danh mục <a href="#portfolio-identities" id="portfolio-identities"></a>

`GET /api/v1/portfolio` và công cụ MCP chỉ đọc `portfolio` thêm `assets` bên cạnh các phần bổ sung tài khoản, ảnh chụp nhanh và PnL hiện có. Mỗi tài sản có `assetId`, `assetKind` (`bundled` hoặc `exchange`), `symbol`, `name`, `amount`, `value`, `unpriced` và `holdings`. `bundled` nghĩa là một danh tính rõ ràng trong sổ đăng ký, dù hiện chỉ được giữ trên một tài khoản. `exchange` nghĩa là một tài sản sàn chưa khớp; id của nó gồm sàn và mã tài sản chính xác. Đừng bao giờ nối các dòng theo `symbol`.

`holdings` giữ lại từng tài khoản, sàn, mã gốc, số lượng, giá, giá trị và cờ thiếu giá. Giá trị và giá là chuỗi số thập phân tính bằng USD. Số lượng tính theo đơn vị của khoản giữ đó; số tiền ví chỉ có giá trị thì là null. Giá trị của một nhóm là tổng giá trị các khoản giữ: 2 UBTC giá 60.000 trên một sàn cộng 1 BTC giá 61.000 trên sàn khác là 181.000, không phải gấp ba một giá tham chiếu. Khi không có giá, số lượng vẫn còn và giá trị đóng góp bằng không; `unpriced` là true nếu có thành phần nào thiếu giá. Giá là giá mới nhất mà goodcryptoX cục bộ của bạn biết; lần đọc này không tự đặt ra giá và không cần dịch vụ của goodcryptoX. Tài khoản bị loại khỏi số dư và tiền demo không có trong tổng tài sản đã kết nối. Phiên bản cũ bỏ qua `assets`; mọi trường cũ giữ nguyên ý nghĩa.

`pnl` trong phản hồi là kết quả các tài khoản đạt được kể từ khi kết nối với goodcryptoX, theo sổ ghi của chính goodcryptoX, như nhau trên mọi sàn: các giao dịch futures đã đóng sau phí, và funding. Mỗi dòng của `accounts` có `connected`, thời điểm bắt đầu tính PnL của tài khoản đó; không có gì trước thời điểm đó nằm trong bất kỳ kỳ nào.

Đọc số liệu vị thế qua chủ đề `positions` (`snapshot` trong MCP). `GET /api/v1/funding?sourceId=&instrumentId=` và công cụ MCP chỉ đọc `funding` trả về các khoản thanh toán có dấu và phần của từng bot. `id` tùy chọn xác định khoản thanh toán của sàn; `asset` là đồng tiền sàn chỉ định cho số tiền trong trường cũ `usdc`. Đừng mặc định số tiền đó là USDC. Các khoản thanh toán chế độ hedge của Binance ở lại tài khoản vì sàn không cung cấp phía. Tương thích: các dòng cũ không có `id` và `asset`; ý nghĩa của mọi trường hiện có được giữ nguyên.

## Câu hỏi thường gặp <a href="#questions" id="questions"></a>

### Có tài liệu OpenAPI không? <a href="#is-there-an-openapi-document" id="is-there-an-openapi-document"></a>

Có: ở `/api/v1/openapi.json` trên địa chỉ bản cài của bạn, được yêu cầu bằng cùng tiêu đề Bearer. Nó chỉ mô tả những gì khóa được gọi.

### API có dùng được từ máy tính khác không? <a href="#does-the-api-work-from-another-computer" id="does-the-api-work-from-another-computer"></a>

Có: chạy trình kết nối ở đó ở chế độ `connect`, và khi nó chạy, nó phục vụ bản cài của bạn ở một địa chỉ cục bộ. [Đường hầm SSH](https://docs.goodcrypto.app/goodcryptox-vi/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead) cũng được.

### Một chương trình có đặt lệnh được không? <a href="#can-a-program-place-orders" id="can-a-program-place-orders"></a>

Có, với khóa **Giao dịch**: `POST /api/v1/orders`, trong tài khoản, thị trường và giới hạn của khóa. Hãy yêu cầu xem trước trước; nó không gửi gì.

### Nếu yêu cầu của tôi hết thời gian chờ thì sao? <a href="#what-happens-if-my-request-times-out" id="what-happens-if-my-request-times-out"></a>

Mất phản hồi không có nghĩa là lệnh đã thất bại: hãy kiểm tra kết quả trước khi thử lại. Khi thử lại, hãy giữ nguyên `requestId` và nội dung để nó không thể đặt cùng một lệnh hai lần.
