# API Guides

> Buy and sell, run strategies and launch a token with the Ora API.

The examples on this page use the `ora()` client from the [Ora API](https://docs.useora.xyz/developers/#a-small-client) page.

### Buy and sell

A trade acts across the wallets of one of your tokens. Each wallet's trade is its own transaction, spaced out so no two land in the same block.

#### 1. Read your positions

`GET /engine/token/{address}/positions` lists each wallet with its token balance (raw units), its SOL and its PnL. Pick the wallets to act with, or let Ora choose.

#### 2. Sell

`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` spreads the amount in proportion to each wallet's holdings, `each` takes the same amount from every wallet, `concentrate` uses the fewest, largest wallets. Asking for more than you hold sells what there is and reports the rest as `shortfall`.

#### 3. Buy

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

Both accept `priorityFee` and `bribeFee` (in SOL) to override the default fees. For an emergency full exit, `POST /engine/token/{address}/position/nuke` sells everything at once.

### Strategies

Strategies trade for you while your script is offline. A limit sell fires when the token's market cap reaches a target:

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

The same shape exists for mirror sells (`/engine/strategies/mirror-sells`, which sell as other wallets buy) and TWAP sells (`/engine/strategies/twap-sells`, spread over time). Each strategy can be listed, edited with `PATCH`, enabled, disabled and deleted; `GET /engine/strategies?mint=…` lists all of a token's strategies. The [Strategies](https://docs.useora.xyz/managing-your-token/trading-page/strategies/) page explains how each type behaves.

#### Buy strategies

Every strategy also runs the other way: these are the app's **Mirror Buy**, **TWAP Buy** and **Limit Buy**. Pass `side: 'buy'` when you create one and it buys the token with the wallets' own quote: SOL or ETH, or the launch's quote token if it has one. The side is set at creation and can't be changed. Without it, a strategy sells.

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

The fields keep their names, but on a buy every amount is in the quote's base units:

| Strategy | What `side: 'buy'` does |
|---|---|
| Mirror | Answers other wallets' **sells** with buys. `sellTokens` is the quote budget, `tokensPerSellMin` the minimum quote per buy. |
| TWAP | Spends `targetTokens` of quote over the duration. |
| Limit | Fires when the market cap **drops** to `triggerMarketCapUsd` and spends `sellTokens` of quote. |

Every strategy you read back carries `side` and `executedAmount`: the tokens sold, or the quote spent, so far. An active strategy reserves what it may still spend. `GET /engine/token/{address}/positions` reports it per wallet as `lockedTokens` (sells) and `lockedQuote` (buys), and a manual buy or sell only spends the rest.

### Launch a token

A launch is the same sequence of calls the app's deploy form makes:

1. `POST /upload/{protocol}`: upload the name, symbol, image and links. Returns the token info ID.
2. `POST /engine/deploy/plan`: get a wallet layout and the full cost estimate for your settings.
3. `POST /engine/prepare`: create the token and its wallets from the plan. Returns the mint.
4. `POST /engine/fund`: returns the funding transactions your wallet signs (see [Transactions you sign](https://docs.useora.xyz/developers/signing-and-streams/#transactions-you-sign)). Send them, then call `POST /engine/fund/confirm`.
5. `POST /engine/launch` with `{ "mint": "…" }`. The launch runs on Ora's side.
6. `GET /engine/tokens/{mint}/stream`: follow it live.

The `prepare` body carries every option of the deploy form (launchpad, quote asset, layers, launchpad-specific settings), so it is long. The easiest way to get one right is to set a launch up in the app first and mirror it. Ask Ora support for the current schema of any route.