# Guides de l'API

> Achetez et vendez, exécutez des stratégies et lancez un token avec l'API Ora.

Les exemples de cette page utilisent le client `ora()` de la page [API Ora](https://docs.useora.xyz/developers/#a-small-client).

### Acheter et vendre

Un trade s'exécute sur les wallets de l'un de vos tokens. Le trade de chaque wallet est une transaction à part, espacée des autres pour que deux d'entre elles n'arrivent jamais dans le même bloc.

#### 1. Lire vos positions

`GET /engine/token/{address}/positions` liste chaque wallet avec son solde en tokens (unités brutes), son SOL et son PnL. Choisissez les wallets avec lesquels agir, ou laissez Ora choisir.

#### 2. Vendre

`POST /engine/token/{address}/position/sell`

```js
const sale = await ora('POST', `/engine/token/${mint}/position/sell`, {
  amountToken: '250000000000',  // raw units, string; 250,000 tokens at 6 decimals
  distribution: 'split',         // split | each | concentrate (default)
  slippage: 10,                  // percent, optional
  // walletAddresses: ['…'],      // optional; default: every holding wallet of the final layer
  // maxDelay: 4000,              // ms of jitter between wallets; must be > 0 with several named wallets
});
// sale.results → [{ walletAddress, status: 'submitted' | 'failed', signature?, error? }]
// sale.summary → { requested, filled, shortfall }  (raw token units, strings)
```

`split` répartit le montant en proportion des avoirs de chaque wallet, `each` prélève le même montant sur chaque wallet, `concentrate` utilise le moins de wallets possible, en prenant les plus gros. Si vous demandez plus que ce que vous détenez, l'appel vend ce qu'il y a et signale le reste dans `shortfall`.

#### 3. Acheter

`POST /engine/token/{address}/position/buy`

```js
const buy = await ora('POST', `/engine/token/${mint}/position/buy`, {
  amountSol: 0.5,          // total to spend, in SOL (the chain's gas asset)
  distribution: 'each',
  slippage: 10,
});
// buy.summary is in lamports: { requested, filled, shortfall }
```

Les deux acceptent `priorityFee` et `bribeFee` (en SOL) pour remplacer les frais par défaut. Pour une sortie totale en urgence, `POST /engine/token/{address}/position/nuke` vend tout d'un coup.

### Stratégies

Les stratégies tradent pour vous pendant que votre script est hors ligne. Une vente Limit se déclenche quand la market cap du token atteint une cible :

`POST /engine/strategies/limit-sells`

```js
await ora('POST', '/engine/strategies/limit-sells', {
  mint,
  strategies: [{
    triggerMarketCapUsd: 250000,
    sellTokens: '100000000000',   // raw token units to sell when it fires
    wallets: [walletA, walletB],   // which of the token's wallets sell
    durationSeconds: 86400,        // optional expiry; omit to keep it until it fires
  }],
});
```

La même structure existe pour les ventes Mirror (`/engine/strategies/mirror-sells`, qui vendent quand d'autres wallets achètent) et les ventes TWAP (`/engine/strategies/twap-sells`, étalées dans le temps). Chaque stratégie peut être listée, modifiée avec `PATCH`, activée, désactivée et supprimée ; `GET /engine/strategies?mint=…` liste toutes les stratégies d'un token. La page [Stratégies](https://docs.useora.xyz/managing-your-token/trading-page/strategies/) explique le comportement de chaque type.

#### Stratégies d'achat

Chaque stratégie fonctionne aussi dans l'autre sens : ce sont les **Mirror Buy**, **TWAP Buy** et **Limit Buy** de l'app. Passez `side: 'buy'` à la création et la stratégie achète le token avec l'actif appairé des wallets : SOL ou ETH, ou le token appairé du lancement s'il en a un. Le côté est fixé à la création et ne peut pas être changé. Sans ce champ, une stratégie vend.

```js
await ora('POST', '/engine/strategies/limit-sells', {
  mint,
  strategies: [{
    side: 'buy',
    triggerMarketCapUsd: 80000,    // buys once the market cap drops to this
    sellTokens: '500000000',       // quote to spend, in base units (here 0.5 SOL)
    wallets: [walletA],
  }],
});
```

Les champs gardent leur nom, mais pour un achat tous les montants sont en unités de base de l'actif appairé :

| Stratégie | Ce que fait `side: 'buy'` |
|---|---|
| Mirror | Répond aux **ventes** des autres wallets par des achats. `sellTokens` est le budget en actif appairé, `tokensPerSellMin` le minimum d'actif appairé par achat. |
| TWAP | Dépense `targetTokens` d'actif appairé sur la durée. |
| Limit | Se déclenche quand la market cap **descend** jusqu'à `triggerMarketCapUsd` et dépense `sellTokens` d'actif appairé. |

Chaque stratégie que vous relisez porte `side` et `executedAmount` : les tokens vendus, ou l'actif appairé dépensé, jusqu'ici. Une stratégie active réserve ce qu'elle peut encore dépenser. `GET /engine/token/{address}/positions` l'indique par wallet dans `lockedTokens` (ventes) et `lockedQuote` (achats), et un achat ou une vente manuels ne dépensent que le reste.

### Lancer un token

Un lancement suit la même séquence d'appels que le formulaire de déploiement de l'app :

1. `POST /upload/{protocol}` : envoyez le nom, le symbole, l'image et les liens. Renvoie l'ID des infos du token.
2. `POST /engine/deploy/plan` : obtenez une organisation des wallets et l'estimation complète du coût pour vos réglages.
3. `POST /engine/prepare` : créez le token et ses wallets à partir du plan. Renvoie le mint.
4. `POST /engine/fund` : renvoie les transactions de financement que votre wallet signe (voir [Transactions que vous signez](https://docs.useora.xyz/developers/signing-and-streams/#transactions-you-sign)). Envoyez-les, puis appelez `POST /engine/fund/confirm`.
5. `POST /engine/launch` avec `{ "mint": "…" }`. Le lancement s'exécute côté Ora.
6. `GET /engine/tokens/{mint}/stream` : suivez-le en direct.

Le corps de `prepare` porte toutes les options du formulaire de déploiement (launchpad, actif appairé, layers, réglages propres au launchpad), il est donc long. Le plus simple pour en obtenir un correct est de configurer d'abord un lancement dans l'app, puis de le reproduire. Demandez au support Ora le schéma à jour de n'importe quelle route.