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

# API

Lis et trade depuis ton programme via l'API locale goodcryptoX, avec les mêmes clés et limites qu'un agent IA.

Ton programme lit et trade sur les exchanges que tu connectes via l'API goodcryptoX décrite par son document OpenAPI. Il utilise les mêmes clés, droits et limites qu'un agent IA ([Clés et limites](https://docs.goodcrypto.app/goodcryptox-fr/goodcryptox-3.0/ai-agents.md#keys-and-limits)).

`POST /api/v1/accounts/{id}/check` (MCP `check_api_key`) relit les autorisations de la clé API d’un compte Binance, Bybit ou Bybit EU, comme **Vérifier à nouveau** sur sa fiche.

Chaque chiffre arrive dans la devise de son trade : prix et valeurs dans la devise de cotation du marché, un PnL dans l'actif que nomme sa ligne, les crédits et `GET /api/v1/portfolio` en USD, les limites d'une clé dans la devise où elles ont été fixées. `GET /api/v1/rates` donne ta devise de référence et son cours pour 1 USD, pour afficher un chiffre comme goodcryptoX.

L'outil MCP `instruments` et `GET /api/v1/instruments?venue=…` incluent le volume connu de chaque marché sur 24 heures (valeur dans la devise de cotation), la variation du prix (en pourcentage) et, si l'exchange le transmet, le prix de la dernière transaction. L'API fournit aussi `instrument-stats/<venue>` via sa [route des sujets](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/runtime/api.md#the-socket). Ces chiffres restent des chaînes décimales. Pour le volume et la variation, null conserve la dernière valeur connue ; le champ facultatif `invalidate` indique les valeurs à effacer. Si `lastPrice` est absent, le prix précédent est conservé pour assurer la compatibilité ; un null explicite l'efface.

Crée une clé dans **Paramètres › MCP & API** ([comment](https://docs.goodcrypto.app/goodcryptox-fr/goodcryptox-3.0/ai-agents.md#connect-any-mcp-app-or-program)). Le côté **API** du bloc affiche trois lignes avec icône de copie : **Adresse**, **Clé** et l'en-tête à envoyer à chaque requête avec la clé choisie : `Authorization: Bearer <your key>`. L'icône copie l'en-tête entier.

<details>

<summary>Exemple de requête API</summary>

Définis `GCX_URL` comme origine accessible au programme et fournis `GCX_KEY` dans son environnement. Cet exemple lit les comptes :

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

Le document OpenAPI est à `$GCX_URL/api/v1/openapi.json`, demandé avec le même en-tête Bearer. Il décrit seulement les appels permis à la clé. Montants, prix et tailles sont des chaînes décimales.

</details>

Les comptes de démonstration et la vue Bybit pour développeurs, y compris les exemples d'envoi avec une clé en lecture seule et de rétablissement, sont réservés aux personnes connectées au panneau. Les clés d'accès et MCP ne peuvent pas utiliser `demoBybitView` ni `demo=1`.

## Depuis un autre ordinateur <a href="#from-another-computer" id="from-another-computer"></a>

Sur un autre ordinateur, lance le connecteur en mode `connect` : il expose l'installation à une adresse locale tant qu'il tourne ([association](https://docs.goodcrypto.app/goodcryptox-fr/goodcryptox-3.0/ai-agents.md#from-another-computer)). Appuie sur **Afficher** près de **Cursor et autres apps** sur cet ordinateur et lance-le avec les valeurs de `env`, sauf `GCX_URL` et `GCX_KEY` : le programme envoie sa propre clé.

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

Il affiche l'adresse de connexion, puis l'adresse API finissant par `/api/v1`. Garde-le actif pendant l'utilisation et utilise la première adresse comme `GCX_URL`, par exemple `http://127.0.0.1:8130`.

<details>

<summary>Démarrages suivants et changements d'adresse</summary>

Ensuite, lance `npx -y goodcryptox-connector@<version>-<build> connect --profile <the profile>` : l'association sauvegardée est réutilisée. Chaque installation a profil et adresse propres. Si l'adresse est occupée, ajoute `--choose-new-address` et copie la nouvelle dans ton programme.

</details>

Déconnecté, les appels échouent sans être gardés pour plus tard. Sans relais, utilise [un tunnel SSH](https://docs.goodcrypto.app/goodcryptox-fr/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead).

Si tu ouvres goodcryptoX à une [adresse domestique](https://docs.goodcrypto.app/goodcryptox-fr/goodcryptox-3.0/readme/set-up-on-your-mac.md#your-home-network), l'**Adresse** du côté **API** est cette adresse : un programme du même réseau y envoie ses requêtes avec sa clé, sans connecteur ni relais, et prend l'adresse sans `/api/v1` comme `GCX_URL`. Utilise-la sur un réseau de confiance ou via ta propre adresse HTTPS de confiance : en HTTP, quelqu'un qui lit le trafic peut copier la clé.

## Envoyer un ordre <a href="#sending-an-order" id="sending-an-order"></a>

Demande d'abord un aperçu ([Vérifier d'abord un ordre](https://docs.goodcrypto.app/goodcryptox-fr/goodcryptox-3.0/ai-agents.md#checking-an-order-first)). Puis `POST /api/v1/orders` avec :

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

Si l'effet de levier du compte n'a pas encore été lu, l'ordre sur un perpétuel est envoyé et l'exchange applique son propre effet de levier ; le reçu de l'aperçu ne contient alors aucune donnée sur les fonds et la marge n'a pas été vérifiée.

Un ordre dont la taille est fixée dans la monnaie de cotation (`"sizeUnit": "quote"`, ou `"coin"` sur un contrat à marge en coins) conserve ce montant : les coins sont recalculés à chaque envoi, au prix d'envoi (un ordre limite à son prix, après chaque changement de prix ; un stop à son déclenchement). Sa ligne affiche le montant sous `cost` et `sizeUnit` à côté de `size`, sa quantité actuelle en coins. Une valeur au moins égale au minimum de l'exchange est arrondie d'un pas de taille vers le haut si l'arrondi inférieur la ferait passer sous le minimum ; `size` sur la ligne peut donc valoir jusqu'à un pas de plus que le montant envoyé. Une taille supérieure à zéro qui n'enverrait rien (inférieure à un pas de taille après cet arrondi) est placée à hauteur d'un pas du coin, et la réponse le précise : `{"id": "o1", "size": "0.001", "sizeUnit": "base"}` ; zéro est refusé. Pour le modifier, `POST /api/v1/orders/{id}/modify` (MCP `modify_order`) accepte `changes.sizeUnit` avec `size` : `{"size": "150", "sizeUnit": "quote"}` fixe le montant à 150, `{"price": "2900"}` conserve le montant au nouveau prix et `size` seul désigne des coins.

Un ordre sous la valeur minimale d'ordre de l'exchange est envoyé tel que tu l'envoies (l'aperçu avertit avec `trade.msgMinNotional`) ; le résultat est la réponse de l'exchange. Les bots font de même : l'entrée et les ordres de moyennage d'un bot DCA et les niveaux d'un Grid sous le minimum sont envoyés. Un ordre refusé par l'exchange devient un ordre en échec du bot (niveau DCA `failed`, compteur `failed` du Grid), renvoyé par Réessayer ou Tout relancer. La ligne du récapitulatif dans l'aperçu du bot marque cet ordre `under` ; `sent` false désigne uniquement un ordre trop petit pour être envoyé. Une ligne Grid avec `sendAll` place chaque niveau ; une ligne sans ce champ (lancée par une version antérieure) retient les niveaux sous le minimum.

Sur un marché à marge en crypto (`contract.method` `"DIV"`), les tailles des ordres, positions et bots sont fournies en contrats avec les données du contrat : USD = contrats × `contract.multiplier`, et le coin = ces USD ÷ prix. Un bot DCA avec `"sizingMode": "coin"` reçoit `entryAmount` et `level1Amount` en monnaie de règlement du contrat (`contract.settlement`) : chaque ordre représente cette quantité de coins à son propre prix, arrondie à l'inférieur aux contrats entiers. `"cost"` utilise les mêmes USD à chaque ordre ; un montant en USD inférieur à un contrat part de la valeur en USD d'un contrat, et chaque niveau est calculé à partir de cette base.

Sur un compte en Mode de couverture, un marché futures a deux identifiants, `…:long` et `…:short`, et le côté ouvre ou ferme : une vente sur le long ou un achat sur le short réduit uniquement cette position, avec ou sans `reduceOnly` ; `reduceOnly: true` sur l'autre côté est refusé (`reduce-only-opens`).

Une réponse perdue ne signifie pas échec : vérifie avant de réessayer. Pour répéter une requête de trading, garde mêmes `requestId` et corps afin de ne pas placer deux fois l'ordre.

`POST /api/v1/margin` ajoute (un `amount` positif) ou retire (un négatif) de la marge isolée sur une position sur Hyperliquid, Binance et Bybit, dans sa monnaie de marge (MCP `change_margin`). Bybit EU prend en charge le spot uniquement. Une clé de trading le fait sur les comptes et marchés que ses limites nomment, comme pour régler l'effet de levier : une clé sans limites, ou pour un autre compte ou marché, reçoit 422 `key.*` et rien n'est envoyé.

Les corps de requêtes et messages de refus de chaque route sont dans le document OpenAPI à `/api/v1/openapi.json`.

## Réglages que toi seul changes <a href="#settings-only-you-change" id="settings-only-you-change"></a>

Certaines routes changent ce que toi seul décides : une clé qui les appelle reçoit 403 `person-only` avec une phrase à te transmettre, et rien n'est envoyé à l'exchange. Leurs outils MCP existent pour qu'un agent puisse te dire quoi faire.

* `POST /api/v1/accounts/{id}/bnb-fees` (`{"on": true}`) active ou désactive **Payer les frais en BNB** sur un compte Binance (MCP `set_bnb_fees`). La ligne du compte dans `GET /api/v1/accounts` l'affiche comme `bnbFees` : `on`, et les réglages derrière, `spot` et `usdm`.

L'interrupteur **Collatéral** d'un coin est lui aussi réservé à toi : `POST /api/v1/accounts/{id}/collateral` répond 403 à une clé et n'a pas d'outil MCP. Un programme lit le réglage dans le sujet `balances` (`perCoinCollateral` : la wallet et, pour chaque coin, `accepted`, `selected` et `fixed` ; null signifie inconnu, jamais désactivé), ou lit un coin directement sur l'exchange avec `GET /api/v1/accounts/{id}/collateral?coin=BTC` (`{coin, accepted, selected}` ; 503 si la lecture échoue ou dépasse dix secondes).

Toi seul peux supprimer un compte : `POST /api/v1/accounts/{sourceId}/remove` fonctionne aussi pour Binance, Bybit et Bybit EU ; aucun outil MCP de suppression de compte n’est proposé.

## Retirer une proposition <a href="#withdrawing-a-proposal" id="withdrawing-a-proposal"></a>

Une clé peut retirer sa proposition d'ordre ou bot en attente : `POST /api/v1/proposals/{id}/withdraw` avec `{"requestId": "..."}`, droit **Proposer** ou plus. Réponse `{"accepted": true}`, identique à la répétition. Une proposition d'une autre clé donne 404 comme inexistante ; lancée, 422 `proposal-launched` ; rejetée, 422 `proposal-rejected`. Le rejet reste à toi : une clé ne rejette pas.

## Listes sur plusieurs comptes <a href="#lists-over-several-accounts" id="lists-over-several-accounts"></a>

`GET /api/v1/lists/positions` et `GET /api/v1/lists/orders` lisent tous les comptes couverts par la liste. Un compte que l'exchange n'a pas pu lire ne masque pas les autres : le `state` de la page reste `live` tant qu'un compte est lu, et `accountStates` donne l'état de chaque compte (`live`, `stale`, `unavailable` ou `waiting` pour sa première lecture), pour que tu saches à qui peuvent appartenir les lignes manquantes. Le `state` de la page n'est `stale` ou `unavailable` que lorsqu'aucun compte n'a pu être lu. Tout annuler, Tout arrêter et Tout fermer répondent pour chaque ordre, bot ou position séparément : ce qui échoue figure dans `refused` avec son message, et le reste est compté dans `count` et `ids`.

## Les ordres échoués d'un bot <a href="#a-bots-failed-orders" id="a-bots-failed-orders"></a>

Un ordre de moyennage DCA ou un ordre de grille refusé n'arrête pas le bot, il ne figure donc ni dans les lignes d'attention ni dans les `items` du bot ; ils ne listent que ce qui arrête un bot ou t'attend. Lis les moyennages échoués d'un bot DCA dans `counters.averagingFailed` de sa ligne, ceux d'une grille dans son `failed` (section suivante), et chaque ordre échoué dans sa ligne d'ordre : `why` est la phrase que le panneau affiche, `errorType` le type qui la sous-tend et `exchangeWords` les mots mêmes de l'exchange ; les outils MCP lisent les mêmes lignes. `errorType` est une chaîne ouverte : affiche les types que tu connais et accepte les nouvelles valeurs. `exchangeWords` contient le `text` du message de l'exchange et un `code` facultatif ; `reason` garde la réponse d'origine. Les deux champs sont absents sans refus de l'exchange et sur les anciens runtimes.

Un ordre échoué d'un bot que le bot renverrait maintenant porte `retry: true` : la personne peut appuyer sur **Réessayer** sur cet ordre. Une clé ne peut pas l'envoyer (`restore-level` ne fait pas partie des commandes de bot d'une clé), dis-le donc à la personne. Sur un bot DCA, c'est un ordre de moyennage ; sans `retry`, le bot le refuserait : en pause, en réparation, après le déclenchement de son stop loss, pendant que son take profit suit le prix, ou à cause d'une tentative précédente du niveau. Sur une grille, c'est la ligne d'ordre de la dernière tentative d'un ordre échoué, et la ligne de l'ordre échoué dans `orders` de la ligne de la grille la porte aussi, avec `error` (notre phrase `why`, et `errorType` et `exchangeWords` quand l'exchange l'a refusé) et `past: true` tant que le replacer l'exécuterait aussitôt. Sans `retry`, la grille ne le placerait pas : elle est en pause, en arrêt, sa position diffère de celle de l'exchange, un élément retient ses nouveaux ordres, le résultat de sa tentative est inconnu, ou un autre ordre occupe ce niveau. Réessayer sur l'ordre d'une grille revient à **Tout relancer** pour cet unique ordre : une lecture de ce qui est libre, et sa réponse est celle de Tout relancer, `{"placed", "left", "needed", "unit"}`, pour cet ordre.

## Ce dont un bot a besoin sur ton compte <a href="#what-a-bot-needs-from-your-account" id="what-a-bot-needs-from-your-account"></a>

Sur perpétuels, `ownFunds` dans la ligne d'un bot est ce dont le bot a besoin sur ton compte pour atteindre son stop (le stop loss d'un DCA), ou pour exécuter son dernier moyennage sans stop, frais compris : le chiffre que `margin.survive` (`margin.toLast`) de l'aperçu a donné quand le cycle a été dimensionné. Un cycle DCA d'une version antérieure garde la valeur de ses ordres ÷ son levier. Celui d'une grille est calculé quand la ligne est servie, grilles terminées comprises. `invested` (Max. prévu) est le plan du plus grand cycle ; un bot sans cycle encore affiche le plan avec lequel il démarrera. Un bot dimensionné en pourcentage du compte est dimensionné pour que son besoin soit ce pourcentage : un DCA en cours à partir de son prochain cycle, une grille à partir du prochain ordre qu'elle place.

## Les ordres échoués d'une grille <a href="#a-grids-failed-orders" id="a-grids-failed-orders"></a>

Une ligne de grille dans `GET /api/v1/bots` contient `failed`, le nombre d'ordres échoués, et, tant qu'il dépasse zéro, `failedWhy` : `money` si tous ont été refusés ou annulés faute de fonds, `other` si aucun ne l'a été, `mixed` sinon. La lecture des ordres liste chaque ordre échoué avec son état.

`POST /api/v1/bots/{id}/command` avec `{"requestId": "...", "kind": "fix-failed"}` les replace, comme **Tout relancer** dans le panneau : une nouvelle lecture des fonds que l'exchange dit libres pour un nouvel ordre, moins tes ordres en cours d'envoi, puis les ordres échoués les plus proches du prix d'abord, dans cette limite. Rien n'est envoyé au-delà de ce que couvre la lecture. La réponse est `{"placed", "left", "needed", "unit"}` : le nombre envoyé, le nombre encore échoué et la quantité de `unit` qui manque au reste (un ordre que l'exchange refuse ensuite réapparaît dans `failed` de la ligne) ; `later` compte ceux laissés pour une autre raison, `past` ceux envoyés aussitôt parce que le prix les avait dépassés. Une grille en pause répond 422 `paused` sans rien placer ; une lecture du solde échouée répond 422 `balance` sans rien placer ; une grille arrêtée répond 409 `state`. C'est une action sur les ordres : une clé peut donc l'envoyer pour une grille qu'elle a créée. Les problèmes du bot ne contiennent plus d'entrée `orders-failed` ; son `facts.failed` est obsolète (voir Les ordres échoués d'un bot). L'outil MCP vient de la même opération.

Un bot encore en arrêt ou en lancement cinq minutes après son début, sans attendre rien de ce que tu as fixé, porte un élément de cause `stuck-stopping`, `stuck-launching` ou `stuck-entry` (une entrée DCA non exécutée) ; `GET /api/v1/bots/{id}` et les lignes d'attention du Dashboard le servent, et il disparaît quand le bot quitte cet état.

## Payer des crédits en $GOOD <a href="#paying-credits-with-good" id="paying-credits-with-good"></a>

Les crédits se paient depuis le wallet de la personne ; un programme ou un agent peut seulement chiffrer, jamais payer. `POST /api/v1/credits/pay` avec `build: false` répond ce qu'un paiement ajouterait ([schéma](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-pay.schema.json)). Demande par le montant du coin, comme le fait Ajouter des crédits : `input` est le montant dans les unités propres du coin, un appel de route, et le paiement dépense exactement cela. Sur Solana, `burn: true` avec n'importe quel coin sauf $GOOD achète du $GOOD dans le même paiement et le brûle, pour la remise $GOOD :

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

Dans la réponse, `quote.credits` donne les crédits en USD et `quote.goodMore` combien de plus que ce qu'achètent les mêmes SOL sans $GOOD (ici environ 9,90 et 0,90). Avec `token` égal au mint de $GOOD lui-même, le $GOOD détenu est brûlé (pas de `burn`). `amount` (crédits voulus) et `spend` (USD à dépenser sur les voies $GOOD) sont toujours acceptés.

Sur Tron, le TRX est échangé contre de l'USDT dans le paiement ; tout autre TRC-20 répond `no-route`.

Dans la réponse, `quote.feeKept` est la part du coin natif du réseau que le paiement laisse pour ses frais, dans ce coin (réseaux EVM et Tron).

## Totaux de l'historique des crédits <a href="#credits-history-totals" id="credits-history-totals"></a>

Une fois que la personne a payé, `POST /api/v1/credits/pay/receipt` avec le `{chain, id}` du paiement (et `coin`, le ticker avec lequel il a été payé, que l'élément d'historique du paiement porte alors sous `paidWith`) lit son statut sur n'importe lequel de nos réseaux ; les crédits apparaissent en général dans `GET /api/v1/credits` quelques secondes après la première confirmation, et un paiement que le réseau abandonne ensuite est repris par une ligne d'historique `reason: "reversed"` (en négatif, avec ses `chain` et `tx`, et les `token`, `amount` et `seq` du paiement sous `payment`). Le `token` d'un paiement est le coin arrivé (après un swap, le token dollar) et ses montants sont dans ce coin ; `paidWith`, quand il est présent, est le coin avec lequel la personne a payé (TRX, ETH, SOL), que la ligne de Paiements nomme ; absent (un paiement fait avant ce champ, ou envoyé depuis l'extérieur de l'app), nomme `token`.

`GET /api/v1/credits` et l'outil MCP `credits` renvoient le même objet supplémentaire facultatif `totals` ([schéma](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-api.schema.json)). `totalPaid`, `paymentCredits`, `grants`, `totalVolume`, `totalFees`, `dailyVolume`, `dailyFees`, `monthlyVolume`, `monthlyFees` et `balanceDifference` sont des chaînes décimales en USD. `firstDay` est la date UTC du premier trade enregistré ou null, `throughDay` est la date UTC d'aujourd'hui et `dayCount` compte les deux extrémités et les jours sans trade. Les moyennes mensuelles valent trente fois les quotidiennes, même avec dix jours d'historique ou à cheval sur deux mois. `paidEstimated` signale les coûts déduits d'paiements. `balanceDifference = paymentCredits + grants - totalFees - balance` ; une valeur non nulle avertit sans jamais bloquer. Les paiements en attente ou annulés sont exclus ; un paiement abandonné par le réseau est retiré de `totalPaid` et `paymentCredits` par sa ligne `reversed`, jamais compté dans `grants`. Si une ancienne version n'a pas les totaux, utilise les jours et l'historique connus et précise que les chiffres sont partiels. `days` et la pagination `?before=YYYY-MM-DD` restent inchangés. Le paiement depuis le wallet reste une action de la personne. Seuls des chiffres complets permettent de signaler un écart de solde. Le montant payé pour chaque paiement en $GOOD est estimé.

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

Utilise `GET /api/v1/trading-volume?before=YYYY-MM-DD` avec la permission de lecture, ou interroge l'outil MCP `trading_volume`. Il montre le montant de tes trades en USD, le nombre d'exécutions, les frais payés et ton PnL réalisé, par compte, marché et selon qui a passé l'ordre, depuis que tu as connecté chaque compte à goodcryptoX. Consulte le [schéma de réponse](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/trading-volume.schema.json).

`totals` couvre toutes les exécutions conservées. `days` montre les 31 derniers jours UTC comportant des exécutions, du plus récent au plus ancien. Pour obtenir la page suivante, passe `next` comme `before` ; ce jour est exclu de la page suivante. Les montants sont des chaînes décimales en USD. Le funding, les transferts et les ordres non exécutés ne comptent pas. Le PnL réalisé en spot n'entre pas dans ces totaux. Les frais de l'exchange et ceux de goodcryptoX sont séparés ; une remise de frais est négative.

`manual` désigne un ordre passé par une personne ou une clé d'accès. `dca` et `grid` désignent les ordres de bots. `gcx` signifie que nous savons que l'ordre est passé par goodcryptoX, mais ne savons plus de quel type d'ordre il s'agissait ni à qui appartenait la clé utilisée. `external` comprend les trades passés hors de goodcryptoX, les liquidations et le désendettement automatique.

Vérifie `state` et `reason` pour chaque compte avant de considérer ses totaux comme complets. Les exécutions antérieures à la connexion d'un compte ne sont pas comptées. Un compte que tu as retiré en gardant son historique, puis remis, garde ce qu'il avait compté et recompte à partir de sa remise. `since` est l'heure de la plus ancienne exécution conservée, en millisecondes ; cela ne garantit pas que toutes les exécutions suivantes sont présentes. Si la lecture de l'historique échoue, le compte reste incomplet jusqu'à ce qu'une nouvelle tentative réussisse. Un compte qui vient d'être connecté reste en attente pendant la lecture de ses exécutions depuis sa connexion. Sur Binance, nous comptons les trades passés hors de goodcryptoX pendant que goodcryptoX fonctionne. Les trades effectués lorsqu'il était éteint, ou perdus lors d'un plantage, peuvent manquer, surtout sur des marchés que nous ne connaissions pas.

`missing` compte les exécutions que nous n'avons pas pu évaluer entièrement en USD : des frais dans une crypto dont l'exchange ne nous a pas donné le prix, ou une exécution sur un marché que nous ne connaissions pas encore. Ce que nous n'avons pas pu évaluer compte pour zéro ; une exécution sur un marché que nous ne connaissions pas encore reste ainsi. `estimated` compte les exécutions évaluées avec un taux que nous avions conservé plutôt qu'un prix au moment de l'exécution. Nous gardons les montants d'origine pour pouvoir améliorer ces chiffres plus tard. `unknownFees` compte les exécutions dont les frais d'exchange sont inconnus, y compris les trades sur actions. `unknownPnl` compte les exécutions sur perpétuels dont le PnL réalisé est inconnu, et non celles dont nous savons qu'il est nul. Les champs de récupération indiquent jusqu'où nous avons vérifié l'historique enregistré. Dans les données qui te sont destinées, `unmatchedFees` compte les débits de crédits que nous n'avons pas pu rattacher à une exécution conservée.

Une clé ne voit que les comptes connectés qu'elle a le droit de lire. Elle voit son propre `keyId` ; les chiffres des autres clés et de la personne sont regroupés sans leurs identifiants. Les chiffres de démo et les comptes effacés sont exclus. Une date qui n'existe pas renvoie 400.

## Identités du portefeuille <a href="#portfolio-identities" id="portfolio-identities"></a>

`GET /api/v1/portfolio` et l'outil MCP en lecture seule `portfolio` ajoutent `assets` à côté des compléments de compte, des instantanés et du PnL existants. Chaque actif a `assetId`, `assetKind` (`bundled` ou `exchange`), `symbol`, `name`, `amount`, `value`, `unpriced` et `holdings`. `bundled` désigne une identité explicite du registre, même si elle n'est détenue pour l'instant que sur un compte. `exchange` désigne un actif d'exchange non associé ; son id contient l'exchange et le code exact de l'actif. Ne réunis jamais des lignes par `symbol`.

`holdings` conserve chaque compte, exchange, code d'origine, quantité, prix, valeur et l'indicateur de prix manquant. Les valeurs et les prix sont des chaînes décimales en USD. Les quantités sont dans les unités de cet avoir ; les montants de wallet qui n'ont qu'une valeur sont nuls. La valeur d'un groupe additionne les valeurs des avoirs : 2 UBTC à 60 000 sur un exchange plus 1 BTC à 61 000 sur un autre font 181 000, et non trois fois un prix de référence. Sans prix, la quantité reste et la valeur contribue pour zéro ; `unpriced` est vrai si un des éléments n'a pas de prix. Les prix sont les derniers connus du runtime local ; cette lecture n'invente pas de prix et n'exige aucun service goodcryptoX. Les comptes exclus des soldes et l'argent de démo sont absents des totaux d'actifs connectés. Les anciens runtimes omettent `assets` ; tous les anciens champs gardent leur sens.

Le `pnl` de la réponse est ce que les comptes ont gagné depuis leur connexion à goodcryptoX, d'après le propre registre de goodcryptoX, de la même façon sur chaque exchange : les trades futures clôturés après frais, et le funding. Chaque ligne de `accounts` porte `connected`, le moment à partir duquel le PnL de ce compte est compté ; rien d'antérieur n'entre dans aucune période.

Lis les chiffres des positions via le topic `positions` (`snapshot` dans MCP). `GET /api/v1/funding?sourceId=&instrumentId=` et l’outil MCP en lecture seule `funding` renvoient les paiements signés et la part de chaque bot. Le champ facultatif `id` identifie le paiement de l’exchange ; `asset` est la monnaie indiquée par l’exchange pour le montant du champ historique `usdc`. Ne suppose jamais que ce montant est en USDC. Les paiements Binance en mode couverture restent au compte, car l’exchange n’indique pas de sens. Compatibilité : les anciennes lignes omettent `id` et `asset` ; les champs existants gardent leur sens.

## Questions fréquentes <a href="#questions" id="questions"></a>

### Y a-t-il un document OpenAPI ? <a href="#is-there-an-openapi-document" id="is-there-an-openapi-document"></a>

Oui : à `/api/v1/openapi.json` sur l'adresse de ton installation, demandé avec le même en-tête Bearer. Il décrit seulement les appels permis à la clé.

### L'API fonctionne-t-elle depuis un autre ordinateur ? <a href="#does-the-api-work-from-another-computer" id="does-the-api-work-from-another-computer"></a>

Oui : lance le connecteur en mode `connect` ; il expose ton installation localement tant qu'il tourne. Un [tunnel SSH](https://docs.goodcrypto.app/goodcryptox-fr/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead) fonctionne aussi.

### Un programme peut-il placer des ordres ? <a href="#can-a-program-place-orders" id="can-a-program-place-orders"></a>

Oui, avec **Trader** : `POST /api/v1/orders` dans les comptes, marchés et limites de la clé. Demande d'abord un aperçu, sans envoi.

### Et si ma requête expire ? <a href="#what-happens-if-my-request-times-out" id="what-happens-if-my-request-times-out"></a>

Une réponse perdue ne signifie pas échec : vérifie avant de réessayer. Garde mêmes `requestId` et corps pour ne pas placer deux fois l'ordre.
