# API 指南

> 使用 Ora API 买入和卖出、运行策略以及发射代币。

本页的示例使用 [Ora API](https://docs.useora.xyz/developers/#a-small-client) 页面中的 `ora()` 客户端。

### 买入和卖出

一次交易会在你某个代币的多个钱包上执行。每个钱包的交易都是一笔独立的交易，并且彼此错开，确保不会有两笔落在同一个区块中。

#### 1. 读取你的持仓

`GET /engine/token/{address}/positions` 会列出每个钱包及其代币余额（原始单位）、SOL 和 PnL。你可以挑选要操作的钱包，也可以交给 Ora 选择。

#### 2. 卖出

`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` 按每个钱包的持仓比例分摊数量，`each` 从每个钱包取相同的数量，`concentrate` 则使用数量最少、持仓最大的钱包。如果请求的数量超过你的持仓，会卖出现有的全部，并把剩余部分报告为 `shortfall`。

#### 3. 买入

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

两者都接受 `priorityFee` 和 `bribeFee`（以 SOL 计），用于覆盖默认费用。如需紧急全部退出，`POST /engine/token/{address}/position/nuke` 会一次性卖出所有持仓。

### 策略

策略会在你的脚本离线时替你交易。Limit 卖出策略会在代币市值达到目标时触发：

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

Mirror 卖出策略（`/engine/strategies/mirror-sells`，在其他钱包买入时卖出）和 TWAP 卖出策略（`/engine/strategies/twap-sells`，随时间分批卖出）也采用同样的结构。每个策略都可以列出、用 `PATCH` 编辑、启用、停用和删除；`GET /engine/strategies?mint=…` 会列出某个代币的所有策略。[策略](https://docs.useora.xyz/managing-your-token/trading-page/strategies/)页面说明了每种类型的运作方式。

#### 买入策略

每种策略也都可以反向运行：它们就是应用中的 **Mirror Buy**、**TWAP Buy** 和 **Limit Buy**。创建策略时传入 `side: 'buy'`，它就会用钱包自己的配对资产买入代币：SOL 或 ETH；如果该发射有配对代币，则使用该配对代币。方向在创建时确定，之后无法更改。不传该字段时，策略为卖出。

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

字段名称保持不变，但在买入策略中，所有数量都以配对资产的最小单位表示：

| 策略 | `side: 'buy'` 的作用 |
|---|---|
| Mirror | 用买入回应其他钱包的 **卖出**。`sellTokens` 是配对资产预算，`tokensPerSellMin` 是每次买入的最小配对资产数量。 |
| TWAP | 在持续时间内花费 `targetTokens` 数量的配对资产。 |
| Limit | 当市值 **跌至** `triggerMarketCapUsd` 时触发，并花费 `sellTokens` 数量的配对资产。 |

你读取到的每个策略都带有 `side` 和 `executedAmount`：即到目前为止已卖出的代币数量，或已花费的配对资产数量。运行中的策略会预留它仍可能花费的部分。`GET /engine/token/{address}/positions` 会按钱包将其报告为 `lockedTokens`（卖出）和 `lockedQuote`（买入），手动买入或卖出只会使用剩余部分。

### 发射代币

发射一个代币，就是依次发起应用部署表单所发起的同一组调用：

1. `POST /upload/{protocol}`：上传名称、符号、图片和链接。返回代币信息 ID。
2. `POST /engine/deploy/plan`：根据你的设置获取钱包布局和完整的成本预估。
3. `POST /engine/prepare`：根据该方案创建代币及其钱包。返回 mint。
4. `POST /engine/fund`：返回需要由你的钱包签名的注资交易（参见[需要你签名的交易](https://docs.useora.xyz/developers/signing-and-streams/#transactions-you-sign)）。发送这些交易，然后调用 `POST /engine/fund/confirm`。
5. `POST /engine/launch`，并带上 `{ "mint": "…" }`。发射在 Ora 一侧执行。
6. `GET /engine/tokens/{mint}/stream`：实时跟踪发射过程。

`prepare` 的请求体包含部署表单的所有选项（发射平台、配对资产、分层、发射平台专属设置），因此很长。最简单的做法是先在应用中配置好一次发射，然后照着它来写。如需任何路由的当前 schema，请向 Ora 支持团队索取。