> For the complete documentation index, see [llms.txt](https://titan-exchange.gitbook.io/titan/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://titan-exchange.gitbook.io/titan/developer-doc/special-order-types/reference/schema.md).

# Order & Execution Schema

Field-by-field reference for the Order, Execution, and balance-row objects, across all four order types.

The objects the API returns. Amounts are integer strings in the token's smallest unit; timestamps are ISO-8601 unless noted as Unix seconds. Treat all ids as opaque.

Every order type shares the base `Order` shape below and adds its own type-specific fields on top.

## Order

Returned by `POST /orders/confirm`, the order lists, and each per-type detail endpoint. The example below is a DCA order — on a trigger order the cycle fields give way to the trigger fields documented further down.

```json
{
  "id": "9b3f1ad0-7c34-4e1f-bcfb-1c9a5a3a7b21",
  "tenantId": "<your tenant uuid>",
  "originatingPartner": { "id": "your-partner-id", "name": "Your Brand" },
  "userId": "<opaque Titan user id>",
  "walletAddress": "GZk2v…",
  "outputRecipientAddress": "GZk2v…",
  "orderType": "dca",
  "status": "active",
  "previousStatus": null,
  "inputMint": "So111…",
  "outputMint": "EPjFW…",
  "totalAmount": "1000000000",
  "amountPerCycle": "100000000",
  "cycleFrequencySeconds": 86400,
  "minOutputPerCycle": null,
  "maxOutputPerCycle": null,
  "cyclesCompleted": 3,
  "totalCycles": 10,
  "amountSpent": "300000000",
  "amountReceived": "150000000",
  "startAt": null,
  "expiresAt": null,
  "nextExecutionAt": "2025-01-04T00:00:00.000Z",
  "lastExecutionAt": "2025-01-03T00:00:00.000Z",
  "lastExecutionTxHash": "<sig or null>",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z",
  "cancelledAt": null,
  "completedAt": null,
  "failedAt": null,
  "failureReason": null,
  "withdrawalStatus": "none",
  "withdrawalTxHash": null,
  "withdrawalRequestedAt": null,
  "withdrawalCompletedAt": null,
  "platformFeeBpsOverride": 50
}
```

| Field                                             | Meaning                                                                                                                                                                                                                                                             |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tenantId`                                        | Your tenant uuid. Present on user-scoped reads; **omitted** on `/partners/me/*` reporting reads.                                                                                                                                                                    |
| `originatingPartner`                              | Resolved partner attribution. Present on user-scoped reads; **omitted** on `/partners/me/*` reads.                                                                                                                                                                  |
| `userId`                                          | The opaque Titan user id (same value `GET /me` returns).                                                                                                                                                                                                            |
| `walletAddress`                                   | The user's **manager** (Titan-managed Solana pubkey).                                                                                                                                                                                                               |
| `outputRecipientAddress`                          | Where swap output lands — the manager (`walletAddress`) or the user's external `userPubkey`. Immutable after create.                                                                                                                                                |
| `orderType`                                       | `dca` \| `stop_loss` \| `take_profit` \| `oco`.                                                                                                                                                                                                                     |
| `status`                                          | `pending` \| `active` \| `executing` \| `pending_modification` \| `paused` \| `completed` \| `cancelled` \| `failed` \| `expired`. A DCA order is `pending` only while waiting on a future `startAt`; trigger orders never use `pending` or `pending_modification`. |
| `previousStatus`                                  | The resting state to render while an order passes through `executing` / `pending_modification`. `null` otherwise.                                                                                                                                                   |
| `cyclesCompleted` / `totalCycles`                 | DCA progress counters.                                                                                                                                                                                                                                              |
| `amountSpent` / `amountReceived`                  | Cumulative input spent and output received across all executions.                                                                                                                                                                                                   |
| `nextExecutionAt` / `lastExecutionAt`             | `null` before the first cycle / after a terminal state. A trigger order has no schedule, so there's nothing to anchor `nextExecutionAt` to.                                                                                                                         |
| `lastExecutionTxHash`                             | Solana signature of the most recent successful execution, or `null`.                                                                                                                                                                                                |
| `failureReason`                                   | Populated when `status = failed`. Short label suitable for surfacing.                                                                                                                                                                                               |
| `withdrawalStatus`                                | `none` \| `pending` \| `completed`. Independent of `status`.                                                                                                                                                                                                        |
| `withdrawalTxHash`                                | Signature of the fund return once `withdrawalStatus = completed`, or `null` (including when an auto-return found nothing to send). Always a real signature or `null` — never a placeholder.                                                                         |
| `withdrawalRequestedAt` / `withdrawalCompletedAt` | Track the withdrawal lifecycle in step with `withdrawalStatus`.                                                                                                                                                                                                     |
| `platformFeeBpsOverride`                          | The per-order fee override, if one was set.                                                                                                                                                                                                                         |

{% hint style="info" %}
Rely only on the fields documented here. A response may carry additional fields while an execution is in flight — treat anything undocumented as internal and subject to change without notice.
{% endhint %}

## Trigger-order fields

`GET /stop-loss/{orderId}`, `/take-profit/{orderId}`, and `/oco/{orderId}` return the base `Order` above plus these. All amounts and prices are strings; all timestamps are ISO-8601 — including `expiresAt`, which you *sent* as Unix seconds.

| Field                                    | Types                      | Meaning                                                                                                                                                    |
| ---------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`                                 | all three                  | The deposit — input tokens sold when the trigger fires.                                                                                                    |
| `triggerPrice`                           | `stop_loss`, `take_profit` | The **initial** trigger, as a pair ratio scaled by `priceDecimals`. Frozen at its creation value, so on a trailing order it is no longer the live trigger. |
| `takeProfitPrice` / `stopLossPrice`      | `oco`                      | The two legs' triggers. `stopLossPrice < takeProfitPrice` always.                                                                                          |
| `priceDecimals`                          | all three                  | Integer `0`–`18`. The scale for every price field on the order.                                                                                            |
| `minOutputAmount`                        | `stop_loss`, `take_profit` | Execution floor. Not supported on `oco`.                                                                                                                   |
| `expiresAt`                              | all three                  | Auto-return fires at expiry.                                                                                                                               |
| `executedPrice`                          | all three                  | The price the fill happened at, once `completed`.                                                                                                          |
| `amountReceived`                         | all three                  | Output received from the fill.                                                                                                                             |
| `trailingStopBps`                        | all three                  | `1`–`9999`. Present when the order is trailing — the stop-loss leg only, on `oco`.                                                                         |
| `currentTriggerPrice`                    | `stop_loss`, `oco`         | The **live** trigger, server-computed. Always present, equal to `triggerPrice` / `stopLossPrice` until the first ratchet. Render this, not `triggerPrice`. |
| `highestObservedPrice`                   | all three                  | The tracked peak. Absent until the first new high — or, on a take-profit, until the trail arms.                                                            |
| `trailingActivated`                      | `take_profit`              | Whether the trail has armed. Take-profit has no `currentTriggerPrice`; compute the derived trigger client-side.                                            |
| `trailingMode`                           | `stop_loss`                | `"pure"` \| `"stop_and_trail"`. A UI-only label that never affects execution.                                                                              |
| `pendingLeg`                             | `oco`                      | `stop_loss` \| `take_profit` — which leg is mid-execution while `executing`. Absent otherwise.                                                             |
| `amountRemaining` / `scaleStepsExecuted` | `take_profit`              | Present on the response; carry no meaning for orders you create.                                                                                           |

{% hint style="warning" %}
**Ignore `entryPrice`, `minProfitBps`, and `scaleSteps`** if they appear on a read — they are legacy fields on older orders and carry no meaning for orders you create.
{% endhint %}

[Trailing Stops](/titan/developer-doc/special-order-types/order-types/trailing.md) covers what each trailing field means per type — they don't behave the same way across the three.

## Execution

Returned by `GET /orders/{orderId}/executions` and `GET /partners/me/executions`. Capped at 500 rows, most recent first.

```json
{
  "id": "c12a8b6f-2f5a-4e26-9c1b-8a4f9e7d1b22",
  "orderId": "9b3f1ad0-…",
  "executionType": "dca_cycle",
  "status": "success",
  "inputAmount": "100000000",
  "outputAmount": "50000000",
  "outputAmountUsd": "5000000",
  "outputAmountUsdDecimals": 6,
  "price": "500000",
  "priceDecimals": 6,
  "txSignature": "<sig>",
  "failureReason": null,
  "executedAt": "2025-01-02T00:00:00.000Z",
  "platformFeeWallet": "FeEa…",
  "platformFeeBps": 50,
  "platformFeeMint": "EPjFW…",
  "platformFeeAmount": "25000"
}
```

| Field             | Notes                                                                                                                                                                                                                                                                            |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `executionType`   | `dca_cycle` (one row per DCA cycle) \| `stop_loss` \| `take_profit_full` — a trigger order writes exactly one row, when it fires. An OCO fill is recorded under its leg's type; there is no `oco` execution type. `take_profit_scaled` appears only on historical scaled orders. |
| `status`          | `pending` (in flight), `success` (confirmed on-chain), `failed` (terminal for that cycle).                                                                                                                                                                                       |
| `price`           | Integer string — a fixed-point number scaled by `priceDecimals`. `price = "500000"` with `priceDecimals = 6` means 0.5 output per input. Don't parse it as a float.                                                                                                              |
| `outputAmountUsd` | Same fixed-point convention with `outputAmountUsdDecimals`. May be `null` if pricing was unavailable at execution time.                                                                                                                                                          |
| `failureReason`   | Short error label when `status = failed`; `null` otherwise. (The on-the-wire field is `failureReason`, not `errorMessage`.)                                                                                                                                                      |
| `platformFee*`    | Snapshot of the fee taken on this execution. All four populate together when a fee was charged; all four are `null` when none was (zero `bps`, or no tenant fee wallet).                                                                                                         |

## Balance row

Returned by `GET /me/balance` inside `data.balances[]`.

| Field                 | Meaning                                                                                                                                                               |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalBalance`        | Raw on-chain balance of the mint in the manager.                                                                                                                      |
| `lockedForFutureTxns` | Reserved by active orders — `totalAmount − amountSpent` of the input mint for DCA, the full unspent `amount` for an armed trigger order. Output mints are not locked. |
| `withdrawalPending`   | Reserved by an in-flight order-level withdrawal.                                                                                                                      |
| `availableToWithdraw` | `max(total − locked − withdrawalPending, 0)`. Source of truth for "withdraw max".                                                                                     |
| `programId`           | One of `native`, `token`, `token-2022`.                                                                                                                               |
| `lockedBreakdown`     | Per-order attribution of the lock: `{ orderId, orderType, status, kind, amount }`. `orderType` is any of `dca`, `stop_loss`, `take_profit`, `oco`.                    |
| `symbol`              | Resolved for `SOL`, `USDC`, `USDT`; otherwise `null` (look it up in your token registry).                                                                             |

## Conventions

Amounts are integer strings in the smallest unit, to avoid JS precision loss. Order, pending-order, and execution ids are UUIDv4; the Titan `userId` is an opaque string. Both legacy SPL Token and Token-2022 mints are supported, detected per mint — though Token-2022 mints with transfer hooks, transfer fees, or unusual extensions may fail to swap or transfer, and the API surfaces an explicit error when they do.

## Related pages

* [Order Types](/titan/developer-doc/special-order-types/order-types.md) — the `config` that produces each of these shapes
* [Lifecycle & Polling](/titan/developer-doc/special-order-types/guides/lifecycle.md) — how `status` and `withdrawalStatus` transition
* [Endpoints](/titan/developer-doc/special-order-types/reference/endpoints.md) — which routes return each object