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

# API

อ่านและเทรดผ่าน API ในเครื่องของ goodcryptoX จากโปรแกรมของคุณเอง ด้วยคีย์และขีดจำกัดเดียวกับเอเจนต์ AI

โปรแกรมของคุณเองอ่านและเทรดบนตลาดที่คุณเชื่อมผ่าน API ของ goodcryptoX ซึ่งมีเอกสาร OpenAPI อธิบายไว้ โปรแกรมใช้คีย์ สิทธิ์ และขีดจำกัดเดียวกับเอเจนต์ AI ([คีย์และขีดจำกัด](https://docs.goodcrypto.app/goodcryptox-th/goodcryptox-3.0/ai-agents.md#keys-and-limits))

`POST /api/v1/accounts/{id}/check` (MCP `check_api_key`) อ่านสิทธิ์คีย์ API ของบัญชี Binance, Bybit หรือ Bybit EU อีกครั้ง เช่นเดียวกับ **ตรวจสอบอีกครั้ง** บนการ์ดบัญชี

ตัวเลขแต่ละตัวมาในสกุลเงินของรายการเทรดนั้น: ราคาและมูลค่าในสกุลเงินอ้างอิงของตลาด PnL ในสินทรัพย์ที่แถวของมันระบุ เครดิตและ `GET /api/v1/portfolio` เป็น USD ขีดจำกัดของคีย์เป็นสกุลเงินที่ใช้ตอนตั้ง `GET /api/v1/rates` ตอบสกุลเงินหลักของคุณและอัตราต่อ 1 USD เพื่อแสดงตัวเลขแบบเดียวกับ goodcryptoX

เครื่องมือ MCP `instruments` และ `GET /api/v1/instruments?venue=…` มีปริมาณซื้อขายใน 24 ชั่วโมงที่ทราบของแต่ละตลาด (มูลค่าในสกุลเงินอ้างอิง) การเปลี่ยนแปลงราคา (เปอร์เซ็นต์) และราคาซื้อขายล่าสุดหากตลาดส่งมา API ยังให้ข้อมูล `instrument-stats/<venue>` ผ่าน[เส้นทางหัวข้อ](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/runtime/api.md#the-socket) ตัวเลขเหล่านี้ยังคงเป็นสตริงทศนิยม สำหรับปริมาณและการเปลี่ยนแปลงราคา null จะเก็บค่าที่ทราบก่อนหน้าไว้ ส่วนฟิลด์ `invalidate` ที่เลือกส่งได้จะระบุค่าที่ต้องล้าง หากไม่มี `lastPrice` จะเก็บราคาเดิมไว้เพื่อให้รองรับการใช้งานแบบเดิม แต่ถ้าส่ง null มาโดยตรงจะล้างราคานั้น

ใน **การตั้งค่า › MCP & API** สร้างคีย์ ([วิธีทำ](https://docs.goodcrypto.app/goodcryptox-th/goodcryptox-3.0/ai-agents.md#connect-any-mcp-app-or-program)); ฝั่ง **API** ของบล็อกเชื่อมต่อจะมีสามบรรทัด แต่ละบรรทัดมีไอคอนคัดลอก: **ที่อยู่**, **คีย์** และเฮดเดอร์ที่โปรแกรมของคุณส่งไปกับทุกคำขอ โดยมีคีย์ที่เลือกอยู่ข้างใน: `Authorization: Bearer <your key>` ไอคอนคัดลอกข้างเฮดเดอร์คัดลอกทั้งบรรทัด

<details>

<summary>ตัวอย่างคำขอ API</summary>

ตั้ง `GCX_URL` เป็น origin ที่โปรแกรมของคุณเข้าถึงได้ และใส่ `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-th/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 ที่ลงท้ายด้วย `/api/v1` เปิดมันทิ้งไว้ขณะที่โปรแกรมของคุณใช้การเชื่อมต่อ และใช้ที่อยู่แรกเป็น `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-th/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead)

เมื่อเปิด goodcryptoX ที่[ที่อยู่ในบ้าน](https://docs.goodcrypto.app/goodcryptox-th/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-th/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` ในแถวอาจมีมูลค่ามากกว่าที่ส่งได้ไม่เกินหนึ่งขั้น ขนาดที่มากกว่าศูนย์แต่จะส่งอะไรไม่ได้ (ต่ำกว่าหนึ่งขั้นขนาดหลังการปัดนั้น) จะวางคำสั่งเป็นหนึ่งขั้นของเหรียญ และคำตอบจะระบุไว้: `{"id": "o1", "size": "0.001", "sizeUnit": "base"}` ส่วนศูนย์จะถูกปฏิเสธ หากต้องการเปลี่ยน `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 นั้น ÷ ราคา บอต DCA ที่กำหนดขนาดด้วย `"sizingMode": "coin"` รับ `entryAmount` และ `level1Amount` เป็นเหรียญชำระราคาของสัญญา (`contract.settlement`) แต่ละคำสั่งใช้เหรียญจำนวนนั้นที่ราคาของคำสั่งเอง แล้วปัดลงเป็นจำนวนสัญญาเต็ม `"cost"` ใช้ USD เท่ากันในทุกคำสั่ง จำนวน USD ที่ต่ำกว่าหนึ่งสัญญาจะเริ่มจากมูลค่า USD ของหนึ่งสัญญา และทุกระดับจะคำนวณตามตัวคูณจากค่านั้น

ในบัญชีที่ใช้ โหมดเฮดจ์ ตลาดฟิวเจอร์สมีสอง ID คือ `…:long` และ `…:short` และฝั่งคำสั่งเป็นตัวกำหนดว่าจะเปิดหรือปิด การขายฝั่งลองหรือซื้อฝั่งชอร์ตจะลดโพซิชันนั้นเท่านั้น ไม่ว่าจะมี `reduceOnly` หรือไม่ ส่วน `reduceOnly: true` ในอีกฝั่งจะถูกปฏิเสธ (`reduce-only-opens`)

การที่คำตอบหายไปหลังส่ง ไม่ได้หมายความว่าคำสั่งล้มเหลว: ตรวจผลลัพธ์ก่อนลองอีกครั้ง เมื่อลองคำขอเทรดซ้ำ ให้คง `requestId` และเนื้อหาเดิมไว้ เพื่อไม่ให้มันวางคำสั่งเดียวกันซ้ำสองครั้ง

`POST /api/v1/margin` เพิ่ม (`amount` เป็นบวก) หรือถอน (เป็นลบ) ไอโซเลตมาร์จิ้น ของโพซิชันบน Hyperliquid, Binance และ Bybit เป็นเหรียญมาร์จิ้นของมัน (MCP `change_margin`) Bybit EU รองรับเฉพาะสปอต คีย์เทรดทำได้บนบัญชีและตลาดที่ลิมิตของมันระบุ เหมือนตอนตั้งเลเวอเรจ: คีย์ที่ไม่มีลิมิต หรือเป็นของบัญชีหรือตลาดอื่น จะได้ 422 `key.*` และไม่มีอะไรถูกส่งไป

เนื้อหาคำขอและข้อความปฏิเสธของทุกเส้นทางอยู่ในเอกสาร OpenAPI ที่ `/api/v1/openapi.json`

## การตั้งค่าที่มีแค่คุณเปลี่ยน <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}`) เปิดหรือปิด **จ่ายค่าธรรมเนียมด้วย BNB** ของบัญชี Binance (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` ซึ่งเป็นจำนวนคำสั่งที่ล้มเหลว และเมื่อมากกว่าศูนย์จะมี `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 มาจากการทำงานเดียวกัน

บอตที่ยังกำลังหยุดหรือกำลังเริ่มหลังเริ่มไปห้านาที และไม่ได้รอสิ่งที่คุณตั้งไว้ จะมีรายการที่มีสาเหตุ `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 `burn: true` กับเหรียญใดก็ได้ที่ไม่ใช่ $GOOD จะซื้อ $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` เป็น mint ของ $GOOD เอง $GOOD ที่มีอยู่จะถูกเผา (ไม่มี `burn`) `amount` (เครดิตที่ต้องการ) และ `spend` (USD ที่จะใช้บนเส้นทางที่ใช้ $GOOD) ยังรับอยู่

บน Tron TRX จะถูกสวอปเป็น USDT ในการชำระนั้น ส่วน TRC-20 อื่นจะได้คำตอบ `no-route`

ในคำตอบ `quote.feeKept` คือจำนวนเหรียญประจำเครือข่ายที่การชำระเหลือไว้เป็นค่าธรรมเนียม เป็นหน่วยของเหรียญนั้น (เครือข่าย EVM และ Tron)

## ยอดรวมประวัติเครดิต <a href="#credits-history-totals" id="credits-history-totals"></a>

หลังผู้ใช้ชำระเงิน `POST /api/v1/credits/pay/receipt` พร้อม `{chain, id}` ของการชำระ (และ `coin` คือทิกเกอร์ที่ใช้จ่าย ซึ่งรายการประวัติของการชำระนั้นจะเก็บไว้เป็น `paidWith`) จะอ่านสถานะได้บนทุกเครือข่ายของเรา เครดิตมักปรากฏใน `GET /api/v1/credits` ไม่กี่วินาทีหลังการยืนยันครั้งแรก และการชำระที่เครือข่ายยกเลิกภายหลังจะถูกหักคืนด้วยแถวประวัติที่มี `reason: "reversed"` (ติดลบ ระบุ `chain` และ `tx` ของมัน รวมถึง `token` `amount` และ `seq` ของการชำระใต้ `payment`) `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` ถ้าไม่ใช่ศูนย์จะแจ้งเตือน แต่ไม่บล็อก ไม่นับการชำระเงินที่รอหรือถูกย้อนกลับ ส่วนการชำระที่เครือข่ายยกเลิกจะถูกหักออกจาก `totalPaid` และ `paymentCredits` ด้วยแถว `reversed` ของมัน และไม่นับใน `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 ได้ไม่ครบ ได้แก่ ค่าธรรมเนียมเป็นเหรียญที่ตลาดไม่ได้ให้ราคามา หรือการเทรดในตลาดที่เรายังไม่รู้จัก ส่วนที่ประเมินไม่ได้จะคิดเป็นศูนย์ และการเทรดในตลาดที่เรายังไม่รู้จักจะคงเป็นแบบนั้น `estimated` นับรายการที่ประเมินด้วยอัตราที่เราเก็บไว้ แทนราคาตอนจับคู่ เราเก็บจำนวนเงินเดิมไว้เพื่อปรับปรุงตัวเลขเหล่านี้ภายหลัง `unknownFees` นับรายการที่ไม่ทราบค่าธรรมเนียมตลาด รวมถึงการเทรดหุ้น `unknownPnl` นับรายการเทรดสัญญาไม่มีกำหนดอายุที่ยังไม่ทราบ PnL ที่รับรู้แล้ว ไม่ใช่รายการที่ทราบว่าเป็นศูนย์ ฟิลด์การกู้คืนแสดงว่าเราตรวจสอบประวัติที่บันทึกไว้ถึงไหนแล้ว สำหรับผู้ใช้ `unmatchedFees` นับการหักเครดิตที่เราเชื่อมโยงกับรายการเทรดที่เก็บไว้ไม่ได้

คีย์เห็นเฉพาะบัญชีที่เชื่อมต่อและได้รับอนุญาตให้อ่านเท่านั้น โดยเห็น `keyId` ของตัวเอง ตัวเลขของคีย์อื่นและผู้ใช้จะรวมกันโดยไม่แสดงตัวระบุ ไม่รวมตัวเลขเดโมและบัญชีที่ลบข้อมูลแล้ว วันที่ที่ไม่มีอยู่จะคืนค่า 400

## ตัวตนของสินทรัพย์ในพอร์ตโฟลิโอ <a href="#portfolio-identities" id="portfolio-identities"></a>

`GET /api/v1/portfolio` และเครื่องมือ MCP `portfolio` แบบอ่านอย่างเดียวเพิ่ม `assets` ไว้ข้างส่วนเสริมของบัญชี สแนปชอต และ PnL ที่มีอยู่ สินทรัพย์แต่ละรายการมี `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 ไม่ใช่สามเท่าของราคาอ้างอิง เมื่อไม่มีราคา จำนวนยังอยู่และมูลค่านับเป็นศูนย์ `unpriced` เป็นจริงถ้าส่วนประกอบใดไม่มีราคา ราคาคือราคาล่าสุดที่ goodcryptoX ในเครื่องของคุณทราบ การอ่านนี้ไม่คิดราคาขึ้นเองและไม่ต้องใช้บริการของ goodcryptoX บัญชีที่ไม่นับในยอดและเงินเดโมจะไม่อยู่ในยอดรวมสินทรัพย์ที่เชื่อมต่อ ระบบรุ่นเก่าไม่มี `assets` ฟิลด์เดิมทั้งหมดยังมีความหมายเหมือนเดิม

`pnl` ในคำตอบคือผลที่บัญชีทำได้นับตั้งแต่เชื่อมต่อกับ goodcryptoX จากบันทึกของ goodcryptoX เอง คิดแบบเดียวกันทุกตลาด ได้แก่ รายการเทรดฟิวเจอร์สที่ปิดแล้วหลังหักค่าธรรมเนียม และ funding แต่ละแถวของ `accounts` มี `connected` ซึ่งคือเวลาที่เริ่มนับ PnL ของบัญชีนั้น ไม่มีสิ่งใดก่อนหน้านั้นอยู่ในช่วงเวลาใดเลย

อ่านตัวเลขโพซิชันผ่านหัวข้อ `positions` (`snapshot` ใน MCP) `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-th/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` และเนื้อหาเดิมไว้ เพื่อไม่ให้มันวางคำสั่งเดียวกันซ้ำสองครั้ง
