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

# API

Baca dan trading lewat API lokal goodcryptoX dari programmu sendiri, dengan key dan limit yang sama seperti agen AI.

Programmu sendiri membaca dan trading di exchange yang kamu hubungkan lewat API goodcryptoX, yang dijelaskan dokumen OpenAPI-nya. Program memakai key, izin, dan limit yang sama seperti agen AI ([Key dan limit](https://docs.goodcrypto.app/goodcryptox-id/goodcryptox-3.0/ai-agents.md#keys-and-limits)).

`POST /api/v1/accounts/{id}/check` (MCP `check_api_key`) membaca ulang izin kunci API akun Binance, Bybit, atau Bybit EU, seperti **Periksa lagi** pada kartunya.

Setiap angka datang dalam mata uang transaksinya sendiri: harga dan nilai dalam mata uang kuotasi pasar, PnL dalam aset yang disebut barisnya, kredit dan `GET /api/v1/portfolio` dalam USD, limit key dalam mata uang saat limit itu diatur. `GET /api/v1/rates` menjawab mata uang dasarmu dan kursnya per 1 USD, untuk menampilkan angka seperti goodcryptoX.

Tool MCP `instruments` dan `GET /api/v1/instruments?venue=…` menyertakan volume 24 jam yang diketahui untuk setiap pasar (nilai dalam mata uang kuotasi), perubahan harga (persen), dan harga transaksi terakhir jika exchange mengirimkannya. API juga menyediakan `instrument-stats/<venue>` melalui [rute topiknya](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/runtime/api.md#the-socket). Angka-angka ini tetap berupa string desimal. Untuk volume dan perubahan harga, null mempertahankan nilai sebelumnya yang diketahui; kolom opsional `invalidate` menyebutkan nilai yang perlu dihapus. Jika `lastPrice` tidak disertakan, harga sebelumnya dipertahankan demi kompatibilitas; null yang dikirim secara eksplisit menghapusnya.

Di **Pengaturan › MCP & API**, buat key ([caranya](https://docs.goodcrypto.app/goodcryptox-id/goodcryptox-3.0/ai-agents.md#connect-any-mcp-app-or-program)); sisi **API** pada blok sambungan lalu punya tiga baris, masing-masing dengan ikon salin: **Alamat**, **Kunci**, dan header yang dikirim programmu pada setiap permintaan, dengan key pilihan di dalamnya: `Authorization: Bearer <your key>`. Ikon salin di samping header menyalinnya utuh.

<details>

<summary>Contoh permintaan API</summary>

Atur `GCX_URL` ke origin yang dijangkau programmu dan berikan `GCX_KEY` di environment-nya. Contoh ini membaca akun:

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

Dokumen OpenAPI ada di `$GCX_URL/api/v1/openapi.json`. Program meminta dokumen itu dengan header Bearer yang sama; deskripsinya hanya memuat apa yang boleh dipanggil key-nya. Jumlah, harga, dan ukuran adalah string desimal.

</details>

Akun demo dan tampilan Bybit untuk pengembang, termasuk contoh pengiriman dengan kunci hanya baca dan pemulihan, hanya untuk orang yang masuk ke panel. Kunci akses dan MCP tidak dapat menggunakan `demoBybitView` atau `demo=1`.

## Dari komputer lain <a href="#from-another-computer" id="from-another-computer"></a>

Untuk program di komputer lain, jalankan konektor di sana dalam mode `connect`-nya: selama berjalan, ia menyajikan instalasimu di alamat lokal ([pemasangan](https://docs.goodcrypto.app/goodcryptox-id/goodcryptox-3.0/ai-agents.md#from-another-computer)). Tekan **Tampilkan** di samping **Cursor dan aplikasi lain** di komputer itu dan jalankan konektor dengan nilai `env`-nya (semua kecuali `GCX_URL` dan `GCX_KEY`; programmu mengirim key-nya sendiri):

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

Ia mencetak alamat sambungan, lalu alamat API yang berakhiran `/api/v1`. Biarkan ia berjalan selama programmu memakai sambungan, dan pakai alamat pertama sebagai `GCX_URL`, misalnya `http://127.0.0.1:8130`.

<details>

<summary>Penjalanan berikutnya dan perubahan alamat</summary>

Pada penjalanan berikutnya, jalankan `npx -y goodcryptox-connector@<version>-<build> connect --profile <the profile>`; pemasangan yang tersimpan dipakai ulang. Setiap instalasi punya profil dan alamatnya sendiri. Jika alamat tersimpannya sedang dipakai, tambahkan `--choose-new-address`, lalu salin alamat baru ke programmu.

</details>

Saat terputus, panggilan gagal; tidak disimpan untuk nanti. Untuk tersambung tanpa relay kami, pakai [tunnel SSH](https://docs.goodcrypto.app/goodcryptox-id/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead).

Jika goodcryptoX dibuka di [alamat rumah](https://docs.goodcrypto.app/goodcryptox-id/goodcryptox-3.0/readme/set-up-on-your-mac.md#your-home-network), **Alamat** di sisi **API** adalah alamat itu: program di jaringan yang sama mengirim permintaannya ke sana dengan key-nya, tanpa konektor atau relay kami, dan memakai alamat tanpa `/api/v1` sebagai `GCX_URL`. Pakai pada jaringan yang kamu percaya, atau lewat alamat HTTPS tepercaya milikmu: lewat HTTP, orang yang bisa membaca trafik bisa menyalin key.

## Mengirim order <a href="#sending-an-order" id="sending-an-order"></a>

Minta pratinjau dulu ([Memeriksa order lebih dulu](https://docs.goodcrypto.app/goodcryptox-id/goodcryptox-3.0/ai-agents.md#checking-an-order-first)). Lalu `POST /api/v1/orders` dengan:

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

Jika leverage akun belum terbaca, order perpetual tetap dikirim dan exchange menerapkan leverage-nya sendiri; tanda terima pratinjau saat itu tidak memuat data dana dan margin belum diperiksa.

Order berukuran dalam mata uang kuotasi (`"sizeUnit": "quote"`, atau `"coin"` pada kontrak bermargin koin) mempertahankan nilainya: koin dihitung ulang setiap pengiriman pada harga pengiriman (limit pada harganya, setelah setiap perubahan harga; stop saat terpicu). Baris order menunjukkan nilai sebagai `cost` dan `sizeUnit` di samping `size`, jumlah koin saat ini. Nilai yang sama atau lebih besar dari minimum exchange dibulatkan satu langkah ukuran ke atas jika pembulatan ke bawah membuatnya di bawah minimum, sehingga nilai `size` pada baris bisa sampai satu langkah lebih besar dari nilai yang dikirim. Ukuran di atas nol yang tidak akan mengirim apa pun (di bawah satu langkah ukuran setelah pembulatan itu) dipasang sebesar satu langkah koin, dan respons menyatakannya: `{"id": "o1", "size": "0.001", "sizeUnit": "base"}`; nol ditolak. Untuk mengubahnya, `POST /api/v1/orders/{id}/modify` (MCP `modify_order`) menerima `changes.sizeUnit` bersama `size`: `{"size": "150", "sizeUnit": "quote"}` menetapkannya menjadi 150, `{"price": "2900"}` mempertahankan nilai pada harga baru, dan `size` saja berarti koin.

Order di bawah nilai minimum order exchange dikirim sesuai yang kamu kirim (pratinjau memberi peringatan dengan `trade.msgMinNotional`); hasilnya adalah jawaban exchange. Bot juga begitu: entry dan order averaging bot DCA serta level Grid di bawah minimum tetap dikirim, dan order yang ditolak exchange menjadi order gagal bot (level DCA `failed`, hitungan `failed` Grid), dikirim lagi lewat Coba lagi atau Perbaiki yang gagal. Baris ringkasan pratinjau bot menandai order seperti itu `under`; `sent` false hanya untuk order yang terlalu kecil untuk dikirim. Baris Grid dengan `sendAll` menempatkan semua level; yang tanpanya (diluncurkan oleh versi sebelumnya) menahan level di bawah minimum.

Di pasar dengan margin koin (`contract.method` `"DIV"`), ukuran order, posisi, dan bot diberikan dalam kontrak beserta data kontraknya: USD = kontrak × `contract.multiplier`, dan koin = USD itu ÷ harga. Bot DCA dengan `"sizingMode": "coin"` menerima `entryAmount` dan `level1Amount` dalam koin penyelesaian kontrak (`contract.settlement`): setiap order adalah jumlah koin itu pada harganya sendiri, dibulatkan ke bawah ke kontrak utuh. `"cost"` memakai jumlah USD yang sama di setiap order; nilai USD di bawah satu kontrak dimulai dari nilai USD satu kontrak, dan setiap level diskalakan dari nilai itu.

Pada akun dengan Mode hedge, pasar futures memiliki dua ID, `…:long` dan `…:short`, dan sisi menentukan buka atau tutup: jual pada long atau beli pada short hanya mengurangi posisi itu, dengan atau tanpa `reduceOnly`; `reduceOnly: true` di sisi lain ditolak (`reduce-only-opens`).

Balasan yang hilang setelah pengiriman tidak berarti order gagal: periksa hasilnya sebelum mencoba lagi. Saat mengulang permintaan trading, pertahankan `requestId` dan body yang sama agar tidak menempatkan order yang sama dua kali.

`POST /api/v1/margin` menambah (`amount` positif) atau mengurangi (negatif) margin terisolasi pada posisi di Hyperliquid, Binance dan Bybit, dalam koin marginnya (MCP `change_margin`). Bybit EU hanya mendukung spot. Key Trading melakukannya di akun dan pasar yang disebut limitnya, seperti saat mengatur leverage: key tanpa limit, atau untuk akun atau pasar lain, mendapat 422 `key.*` dan tidak ada yang dikirim.

Body permintaan dan pesan penolakan setiap rute ada di dokumen OpenAPI di `/api/v1/openapi.json`.

## Pengaturan yang hanya kamu ubah <a href="#settings-only-you-change" id="settings-only-you-change"></a>

Beberapa rute mengubah hal yang hanya kamu tentukan: kunci yang memanggilnya mendapat 403 `person-only` dengan kalimat untuk diteruskan kepadamu, dan tidak ada yang dikirim ke bursa. Alat MCP-nya ada agar agen bisa memberi tahu kamu apa yang harus dilakukan.

* `POST /api/v1/accounts/{id}/bnb-fees` (`{"on": true}`) menyalakan atau mematikan **Bayar biaya dengan BNB** untuk akun Binance (MCP `set_bnb_fees`). Baris akun di `GET /api/v1/accounts` menampilkannya sebagai `bnbFees`: `on`, dan pengaturan di baliknya, `spot` dan `usdm`.

Sakelar **Jaminan** suatu coin juga hanya untukmu: `POST /api/v1/accounts/{id}/collateral` menjawab key dengan 403 dan tidak punya alat MCP. Program membaca pengaturannya di topik `balances` (`perCoinCollateral`: wallet, serta `accepted`, `selected`, dan `fixed` untuk setiap coin; null berarti tidak diketahui, bukan Nonaktif), atau membaca satu coin langsung dari exchange dengan `GET /api/v1/accounts/{id}/collateral?coin=BTC` (`{coin, accepted, selected}`; 503 jika pembacaan gagal atau memakan waktu lebih dari sepuluh detik).

Hanya kamu yang dapat menghapus akun: `POST /api/v1/accounts/{sourceId}/remove` juga melayani Binance, Bybit, dan Bybit EU; tidak ada alat MCP untuk menghapus akun.

## Menarik kembali usulan <a href="#withdrawing-a-proposal" id="withdrawing-a-proposal"></a>

Key yang mengusulkan order atau bot bisa menariknya selagi menunggumu: `POST /api/v1/proposals/{id}/withdraw` dengan `{"requestId": "..."}`, cakupan **Usul** atau lebih tinggi. Jawabannya `{"accepted": true}`; bertanya lagi menjawab hal yang sama. Usulan key lain dijawab 404, seolah tidak ada; yang sudah kamu luncurkan dijawab 422 `proposal-launched`, dan yang kamu tolak 422 `proposal-rejected`. Menolak tetap hakmu: key tidak bisa menolak.

## Daftar lintas akun <a href="#lists-over-several-accounts" id="lists-over-several-accounts"></a>

`GET /api/v1/lists/positions` dan `GET /api/v1/lists/orders` membaca setiap akun yang dicakup daftar. Satu akun yang tidak bisa dibaca dari exchange tidak menyembunyikan akun lain: `state` halaman tetap `live` selama ada akun yang terbaca, dan `accountStates` memberikan status setiap akun (`live`, `stale`, `unavailable`, atau `waiting` pada pembacaan pertama), agar kamu tahu baris akun mana yang mungkin hilang. `state` halaman hanya menjadi `stale` atau `unavailable` jika tidak ada akun yang bisa dibaca. Batalkan semua, Hentikan semua, dan Tutup semua menjawab setiap order, bot, atau posisi secara terpisah: yang gagal tercantum dalam `refused` dengan pesannya, dan sisanya dihitung dalam `count` dan `ids`.

## Order bot yang gagal <a href="#a-bots-failed-orders" id="a-bots-failed-orders"></a>

Order averaging DCA atau order grid yang ditolak tidak menghentikan bot, jadi tidak muncul di baris perhatian maupun di `items` bot; di sana hanya ada yang menghentikan bot atau menunggumu. Baca order averaging yang gagal dari bot DCA di `counters.averagingFailed` pada barisnya, milik grid di `failed`-nya (bagian berikutnya), dan tiap order yang gagal dari baris ordernya: `why` adalah kalimat yang ditampilkan panel, `errorType` tipe di baliknya, dan `exchangeWords` kata-kata asli exchange; tool MCP membaca baris yang sama. `errorType` adalah string terbuka: tampilkan tipe yang kamu kenal dan izinkan nilai baru. `exchangeWords` berisi `text` pesan exchange dan `code` opsional; `reason` menyimpan balasan aslinya. Kedua bidang tidak ada tanpa penolakan exchange dan pada runtime lama.

Order gagal milik bot yang akan dikirim ulang bot sekarang membawa `retry: true`: orang itu bisa menekan **Coba lagi** pada order tersebut. Key tidak bisa mengirimnya (`restore-level` tidak termasuk perintah bot milik key), jadi beri tahu orangnya. Pada bot DCA itu order averaging; tanpa `retry` bot akan menolaknya: dijeda, dalam perbaikan, setelah stop loss-nya terpicu, saat take profit-nya mengikuti, atau karena percobaan sebelumnya pada level itu. Pada grid itu adalah baris order dari percobaan terakhir sebuah order yang gagal, dan baris order gagal itu di `orders` pada baris grid juga membawanya, dengan `error` (kalimat kami `why`, serta `errorType` dan `exchangeWords` bila exchange menolaknya) dan `past: true` selama memasangnya lagi akan langsung terisi. Tanpa `retry` grid tidak akan memasangnya: grid dijeda, sedang berhenti, posisinya berbeda dari posisi exchange, sebuah item menahan order barunya, hasil percobaannya belum diketahui, atau order lain menempati level itu. Coba lagi pada order grid adalah **Perbaiki yang gagal** untuk satu order itu: satu kali baca dana yang bebas, dan jawabannya adalah jawaban Perbaiki yang gagal, `{"placed", "left", "needed", "unit"}`, untuk order itu.

## Yang dibutuhkan bot dari akunmu <a href="#what-a-bot-needs-from-your-account" id="what-a-bot-needs-from-your-account"></a>

Di perpetual, `ownFunds` pada baris bot adalah yang dibutuhkan bot dari akunmu untuk mencapai stop-nya (stop loss DCA), atau untuk mengisi order averaging terakhirnya jika tanpa stop, termasuk fee: angka yang diberikan `margin.survive` (`margin.toLast`) pada pratinjau saat siklus ditentukan ukurannya. Siklus DCA dari versi sebelumnya mempertahankan nilai order-nya ÷ leverage-nya. Milik Grid dihitung saat baris disajikan, termasuk grid yang sudah selesai. `invested` (Maks. rencana) adalah rencana siklus terbesar; bot yang belum punya siklus menampilkan rencana yang akan dipakainya untuk mulai. Bot yang ukurannya ditentukan sebagai persen dari akun diukur agar kebutuhannya sebesar persen itu: DCA yang berjalan mulai siklus berikutnya, Grid mulai dari order berikutnya yang dipasangnya.

## Order grid yang gagal <a href="#a-grids-failed-orders" id="a-grids-failed-orders"></a>

Baris grid dalam `GET /api/v1/bots` memuat `failed`, jumlah order yang gagal, dan selama di atas nol, `failedWhy`: `money` jika semua ditolak atau dibatalkan karena dana, `other` jika tidak ada yang begitu, dan `mixed` untuk lainnya. Pembacaan order mencantumkan setiap order yang gagal beserta statusnya.

`POST /api/v1/bots/{id}/command` dengan `{"requestId": "...", "kind": "fix-failed"}` memasangnya lagi, sama seperti **Perbaiki yang gagal** di panel: membaca ulang dana yang menurut exchange bebas untuk order baru, dikurangi ordermu yang sedang dikirim, lalu memasang order yang gagal mulai dari yang terdekat dengan harga, sejauh dananya cukup. Tidak mengirim apa pun yang tidak tercakup pembacaan itu. Jawabannya `{"placed", "left", "needed", "unit"}`: berapa yang dikirim, berapa yang masih gagal, dan berapa tambahan `unit` yang dibutuhkan sisanya (order yang kemudian ditolak exchange muncul lagi pada `failed` di baris); `later` menghitung yang ditinggalkan karena alasan lain, `past` yang langsung dikirim karena harga sudah melewatinya. Grid yang dijeda menjawab 422 `paused` tanpa memasang apa pun; pembacaan saldo yang gagal menjawab 422 `balance` tanpa memasang apa pun; grid yang dihentikan menjawab 409 `state`. Ini aksi order, jadi key boleh mengirimnya untuk grid yang dibuatnya. Masalah bot tidak lagi memuat item `orders-failed`; `facts.failed`-nya sudah usang (lihat Order bot yang gagal). Alat MCP berasal dari operasi yang sama.

Bot yang masih dihentikan atau diluncurkan lima menit setelah dimulai, tanpa menunggu apa pun yang kamu atur, membawa item dengan penyebab `stuck-stopping`, `stuck-launching` atau `stuck-entry` (entry DCA belum terisi); `GET /api/v1/bots/{id}` dan baris perhatian di Dashboard menyajikannya, dan item itu hilang saat bot keluar dari keadaan itu.

## Membayar kredit dengan $GOOD <a href="#paying-credits-with-good" id="paying-credits-with-good"></a>

Kredit dibayar dari wallet milik orangnya sendiri; program atau agen hanya bisa meminta kutipan, tidak pernah membayar. `POST /api/v1/credits/pay` dengan `build: false` menjawab berapa yang akan ditambahkan sebuah pembayaran ([skema](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-pay.schema.json)). Tanyakan menurut jumlah koin, seperti Tambah kredit: `input` adalah jumlah dalam satuan koin itu sendiri, satu panggilan rute, dan pembayaran membelanjakan persis itu. Di Solana, `burn: true` dengan koin apa pun selain $GOOD membeli $GOOD dalam pembayaran yang sama dan membakarnya, untuk diskon $GOOD:

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

Pada jawaban, `quote.credits` adalah kredit dalam USD dan `quote.goodMore` berapa lebih banyak daripada yang dibeli SOL yang sama tanpa $GOOD (di sini sekitar 9,90 dan 0,90). Dengan `token` berupa mint $GOOD sendiri, $GOOD yang dipegang dibakar (tanpa `burn`). `amount` (kredit yang diinginkan) dan `spend` (USD yang dibelanjakan di jalur $GOOD) tetap diterima.

Di Tron, TRX ditukar ke USDT dalam pembayaran; TRC-20 lain apa pun dijawab dengan `no-route`.

Dalam jawaban, `quote.feeKept` adalah berapa banyak koin asli jaringan yang disisakan pembayaran untuk biayanya, dalam koin itu (jaringan EVM dan Tron).

## Total riwayat kredit <a href="#credits-history-totals" id="credits-history-totals"></a>

Setelah orang itu membayar, `POST /api/v1/credits/pay/receipt` dengan `{chain, id}` pembayaran (dan `coin`, ticker yang dipakai membayar, yang kemudian dibawa item riwayat pembayaran sebagai `paidWith`) membaca statusnya di jaringan mana pun milik kami; kredit biasanya muncul di `GET /api/v1/credits` beberapa detik setelah konfirmasi pertama, dan pembayaran yang kemudian dibatalkan jaringan ditarik kembali lewat baris riwayat dengan `reason: "reversed"` (di bawah nol, menyebut `chain` dan `tx`-nya, serta `token`, `amount`, dan `seq` pembayaran di bawah `payment`). `token` sebuah pembayaran adalah koin yang tiba (setelah swap, token dolar) dan angkanya dalam koin itu; `paidWith`, bila ada, adalah koin yang dipakai orang itu untuk membayar (TRX, ETH, SOL), yang disebut baris Pembayaran; bila tidak ada (pembayaran sebelum bidang ini, atau dikirim dari luar aplikasi), sebutkan `token`.

`GET /api/v1/credits` dan MCP `credits` mengembalikan objek tambahan opsional `totals` yang sama ([skema](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-api.schema.json)). `totalPaid`, `paymentCredits`, `grants`, `totalVolume`, `totalFees`, `dailyVolume`, `dailyFees`, `monthlyVolume`, `monthlyFees`, dan `balanceDifference` berupa string desimal dalam USD. `firstDay` adalah tanggal UTC transaksi pertama yang tercatat atau null, `throughDay` tanggal UTC hari ini, dan `dayCount` menghitung kedua ujung serta hari tanpa transaksi. Rata-rata bulanan berarti tiga puluh kali rata-rata harian, meski baru ada sepuluh hari riwayat atau melewati pergantian bulan. `paidEstimated` menandai biaya pembayaran yang disimpulkan. `balanceDifference = paymentCredits + grants - totalFees - balance`; nilai bukan nol memberi peringatan, tidak pernah memblokir. Pembayaran yang menunggu dan dibatalkan dikecualikan; pembayaran yang dibatalkan jaringan dikeluarkan dari `totalPaid` dan `paymentCredits` lewat baris `reversed`-nya, dan tidak pernah dihitung di `grants`. Jika versi lama tidak memiliki total, gunakan hari dan riwayat yang diketahui serta nyatakan bahwa angkanya parsial. `days` dan paginasi `?before=YYYY-MM-DD` tetap sama. Pembayaran dari dompet tetap dilakukan oleh orangnya sendiri. Peringatan selisih saldo hanya muncul jika angkanya lengkap. Biaya tunai setiap pembayaran $GOOD adalah perkiraan.

## Volume trading <a href="#trading-volume" id="trading-volume"></a>

Gunakan `GET /api/v1/trading-volume?before=YYYY-MM-DD` dengan izin baca, atau tanyakan lewat alat MCP `trading_volume`. Hasilnya menunjukkan nilai transaksimu dalam USD, jumlah transaksi yang terisi, biaya yang kamu bayar, dan PnL terealisasi, menurut akun, pasar, dan siapa yang memasang order, sejak kamu menghubungkan tiap akun ke goodcryptoX. Lihat [skema respons](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/trading-volume.schema.json).

`totals` mencakup semua transaksi yang kami simpan. `days` menampilkan 31 hari UTC terakhir yang memiliki transaksi, dari yang terbaru. Untuk mengambil halaman berikutnya, kirim `next` sebagai `before`; hari itu tidak disertakan di halaman berikutnya. Nominal berupa string desimal dalam USD. Funding, transfer, dan order yang belum terisi tidak dihitung. PnL terealisasi dari spot tidak masuk ke total ini. Biaya exchange dan biaya goodcryptoX dipisahkan; pengembalian biaya bernilai negatif.

`manual` berarti order yang dipasang oleh seseorang atau kunci akses. `dca` dan `grid` berarti order bot. `gcx` berarti kami tahu order berasal dari goodcryptoX, tetapi tidak lagi tahu jenis order atau kunci siapa yang memasangnya. `external` mencakup transaksi di luar goodcryptoX, likuidasi, dan pengurangan leverage otomatis.

Periksa `state` dan `reason` setiap akun sebelum menganggap totalnya lengkap. Transaksi dari sebelum kamu menghubungkan akun tidak dihitung. Jika kamu menghapus akun dengan riwayat tetap disimpan lalu memulihkannya, akun itu mempertahankan apa yang sudah dihitungnya dan menghitung lagi sejak dipulihkan. `since` adalah waktu transaksi tertua yang kami simpan, dalam milidetik; ini tidak menjamin semua transaksi setelahnya tersedia. Jika pembacaan riwayat gagal, data akun tetap tidak lengkap sampai percobaan ulang berhasil. Akun yang baru dihubungkan tetap menunggu saat kami membaca transaksi sejak akun itu dihubungkan. Di Binance, kami menghitung transaksi di luar goodcryptoX selama goodcryptoX berjalan. Transaksi saat goodcryptoX mati, atau yang hilang saat terjadi crash, bisa tidak tercatat, terutama di pasar yang belum kami ketahui.

`missing` menghitung transaksi yang tidak bisa kami nilai sepenuhnya dalam USD: biaya dalam koin yang harganya tidak diberikan exchange, atau transaksi di pasar yang belum kami kenal. Yang tidak bisa kami nilai dihitung nol; transaksi di pasar yang belum kami kenal tetap seperti itu. `estimated` menghitung transaksi yang dinilai dengan kurs yang kami simpan, bukan harga saat fill terjadi. Kami menyimpan nominal asli agar bisa memperbaiki angka ini nanti. `unknownFees` menghitung transaksi yang biaya exchange-nya tidak diketahui, termasuk transaksi saham. `unknownPnl` menghitung transaksi perpetual yang PnL terealisasinya tidak diketahui, bukan yang sudah diketahui bernilai nol. Kolom pemulihan menunjukkan sejauh mana kami telah memeriksa riwayat tersimpan. Untuk pengguna, `unmatchedFees` menghitung pemotongan kredit yang tidak bisa kami hubungkan dengan transaksi tersimpan.

Kunci hanya melihat akun terhubung yang boleh dibacanya. Kunci melihat `keyId` miliknya sendiri; angka milik kunci lain dan pengguna digabungkan tanpa identitas mereka. Angka demo dan akun yang dihapus tidak disertakan. Tanggal yang tidak ada mengembalikan 400.

## Identitas portofolio <a href="#portfolio-identities" id="portfolio-identities"></a>

`GET /api/v1/portfolio` dan tool MCP read-only `portfolio` menambahkan `assets` di samping suplemen akun, snapshot, dan PnL yang sudah ada. Setiap aset punya `assetId`, `assetKind` (`bundled` atau `exchange`), `symbol`, `name`, `amount`, `value`, `unpriced`, dan `holdings`. `bundled` berarti identitas eksplisit dari registri, meski saat ini hanya dipegang di satu akun. `exchange` berarti aset exchange yang belum dipetakan; id-nya memuat exchange dan kode aset persisnya. Jangan pernah menggabungkan baris berdasarkan `symbol`.

`holdings` menyimpan setiap akun, exchange, kode asli, jumlah, harga, nilai, dan penanda harga yang belum ada. Nilai dan harga adalah string desimal dalam USD. Jumlah dalam satuan aset itu; jumlah wallet yang hanya punya nilai bernilai null. Nilai sebuah grup menjumlahkan nilai tiap aset: 2 UBTC seharga 60.000 di satu exchange ditambah 1 BTC seharga 61.000 di exchange lain adalah 181.000, bukan tiga kali harga acuan. Tanpa harga, jumlahnya tetap ada dan nilainya menyumbang nol; `unpriced` bernilai true jika ada bagian yang belum punya harga. Harga adalah yang terakhir diketahui di runtime lokal; bacaan ini tidak mengarang harga dan tidak memerlukan layanan goodcryptoX. Akun yang dikecualikan dari saldo dan uang demo tidak ada di total aset terhubung. Runtime lama tidak menyertakan `assets`; semua bidang lama tetap bermakna sama.

`pnl` dalam jawaban adalah hasil akun sejak dihubungkan ke goodcryptoX, dari catatan goodcryptoX sendiri, sama di setiap bursa: transaksi futures yang ditutup setelah biaya, dan funding. Setiap baris `accounts` membawa `connected`, saat PnL akun itu mulai dihitung; tidak ada yang sebelum itu masuk ke periode mana pun.

Baca angka posisi melalui topik `positions` (`snapshot` di MCP). `GET /api/v1/funding?sourceId=&instrumentId=` dan alat MCP hanya baca `funding` mengembalikan pembayaran bertanda serta bagian setiap bot. `id` opsional mengidentifikasi pembayaran bursa; `asset` adalah koin yang dinyatakan bursa untuk jumlah dalam kolom lama `usdc`. Jangan pernah menganggap jumlah itu dalam USDC. Pembayaran mode hedge Binance tetap pada akun karena bursa tidak memberikan sisi. Kompatibilitas: baris lama tidak memiliki `id` dan `asset`; semua kolom yang ada tetap memiliki arti yang sama.

## Pertanyaan <a href="#questions" id="questions"></a>

### Apakah ada dokumen OpenAPI? <a href="#is-there-an-openapi-document" id="is-there-an-openapi-document"></a>

Ya: di `/api/v1/openapi.json` pada alamat instalasimu, diminta dengan header Bearer yang sama. Ia hanya menjelaskan apa yang boleh dipanggil key.

### Apakah API bekerja dari komputer lain? <a href="#does-the-api-work-from-another-computer" id="does-the-api-work-from-another-computer"></a>

Ya: jalankan konektor di sana dalam mode `connect`-nya, dan selama berjalan ia menyajikan instalasimu di alamat lokal. [Tunnel SSH](https://docs.goodcrypto.app/goodcryptox-id/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead) juga bisa.

### Bisakah program menempatkan order? <a href="#can-a-program-place-orders" id="can-a-program-place-orders"></a>

Bisa, dengan key **Trading**: `POST /api/v1/orders`, dalam akun, market, dan limit key. Minta pratinjau dulu; ia tidak mengirim apa pun.

### Apa yang terjadi kalau permintaanku timeout? <a href="#what-happens-if-my-request-times-out" id="what-happens-if-my-request-times-out"></a>

Balasan yang hilang tidak berarti order gagal: periksa hasilnya sebelum mencoba lagi. Saat mengulang, pertahankan `requestId` dan body yang sama agar tidak menempatkan order yang sama dua kali.
