# Guías de la API

> Compra y vende, ejecuta estrategias y lanza un token con la API de Ora.

Los ejemplos de esta página usan el cliente `ora()` de la página [API de Ora](https://docs.useora.xyz/developers/#a-small-client).

### Comprar y vender

Una operación actúa sobre las wallets de uno de tus tokens. La operación de cada wallet es una transacción propia, espaciada de modo que nunca caigan dos en el mismo bloque.

#### 1. Lee tus posiciones

`GET /engine/token/{address}/positions` lista cada wallet con su saldo de tokens (unidades en bruto), su SOL y su PnL. Elige las wallets con las que actuar, o deja que Ora elija.

#### 2. Vende

`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` reparte la cantidad en proporción a los holdings de cada wallet, `each` toma la misma cantidad de cada wallet, `concentrate` usa el menor número posible de wallets, las más grandes. Si pides más de lo que tienes, se vende lo que hay y el resto se indica como `shortfall`.

#### 3. Compra

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

Ambas aceptan `priorityFee` y `bribeFee` (en SOL) para sustituir las comisiones por defecto. Para una salida total de emergencia, `POST /engine/token/{address}/position/nuke` vende todo de una vez.

### Estrategias

Las estrategias operan por ti mientras tu script está desconectado. Una venta limit se dispara cuando el market cap del token alcanza un objetivo:

`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 misma estructura existe para las ventas mirror (`/engine/strategies/mirror-sells`, que venden a medida que otras wallets compran) y las ventas TWAP (`/engine/strategies/twap-sells`, repartidas en el tiempo). Cada estrategia se puede listar, editar con `PATCH`, activar, desactivar y eliminar; `GET /engine/strategies?mint=…` lista todas las estrategias de un token. La página [Estrategias](https://docs.useora.xyz/managing-your-token/trading-page/strategies/) explica cómo se comporta cada tipo.

#### Estrategias de compra

Todas las estrategias funcionan también en el otro sentido: son los **Mirror Buy**, **TWAP Buy** y **Limit Buy** de la app. Pasa `side: 'buy'` al crear una y comprará el token con el activo emparejado de las propias wallets: SOL o ETH, o el token emparejado del lanzamiento si tiene uno. El lado se fija al crearla y no se puede cambiar. Sin él, la estrategia vende.

```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],
  }],
});
```

Los campos conservan sus nombres, pero en una compra todas las cantidades van en unidades base del activo emparejado:

| Estrategia | Qué hace `side: 'buy'` |
|---|---|
| Mirror | Responde con compras a las **ventas** de otras wallets. `sellTokens` es el presupuesto en activo emparejado, `tokensPerSellMin` el mínimo de activo emparejado por compra. |
| TWAP | Gasta `targetTokens` de activo emparejado a lo largo de la duración. |
| Limit | Se dispara cuando el market cap **baja** hasta `triggerMarketCapUsd` y gasta `sellTokens` de activo emparejado. |

Cada estrategia que lees lleva `side` y `executedAmount`: los tokens vendidos, o el activo emparejado gastado, hasta el momento. Una estrategia activa reserva lo que aún puede gastar. `GET /engine/token/{address}/positions` lo indica por wallet como `lockedTokens` (ventas) y `lockedQuote` (compras), y una compra o una venta manual solo gasta el resto.

### Lanzar un token

Un lanzamiento es la misma secuencia de llamadas que hace el formulario de despliegue de la app:

1. `POST /upload/{protocol}`: sube el nombre, el símbolo, la imagen y los enlaces. Devuelve el ID de la información del token.
2. `POST /engine/deploy/plan`: obtén una distribución de wallets y la estimación completa del costo para tu configuración.
3. `POST /engine/prepare`: crea el token y sus wallets a partir del plan. Devuelve el mint.
4. `POST /engine/fund`: devuelve las transacciones de financiación que firma tu wallet (consulta [Transacciones que firmas tú](https://docs.useora.xyz/developers/signing-and-streams/#transactions-you-sign)). Envíalas y luego llama a `POST /engine/fund/confirm`.
5. `POST /engine/launch` con `{ "mint": "…" }`. El lanzamiento se ejecuta del lado de Ora.
6. `GET /engine/tokens/{mint}/stream`: síguelo en tiempo real.

El cuerpo de `prepare` lleva todas las opciones del formulario de despliegue (launchpad, activo emparejado, capas, ajustes específicos del launchpad), así que es largo. La forma más fácil de acertar es configurar primero un lanzamiento en la app y reproducirlo. Pide al soporte de Ora el esquema actual de cualquier ruta.