> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aultblockchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Perpetual Accounts & History

> [!NOTE]
>
> **Testnet-Only.** Use `https://test-dex-api.cloud.aultblockchain.xyz` for these endpoints and the matching Testnet chain for signed actions. This product is not available on Mainnet.

Query an owner's cross and isolated accounts, orders and financial history. These reads require no signature and do not move collateral or place orders. See [Perpetuals](https://docs.aultblockchain.com/ault-dex/perpetuals.md) for margin, funding and liquidation rules.

## Routes and filters

Every path starts with `/api/v1/perp/owners/{owner}`. `owner` is a wallet address in bech32 or EVM hex form. Use returned derived `accountId` values unchanged in `account_id` filters.

| GET suffix | Optional filters | Body |
| - | - | - |
| `/accounts` | None | `Account[]` |
| `/positions` | `account_id`, `market_id` | `Position[]` |
| `/margin-configs` | `market_id` | `MarginConfig[]` |
| `/orders` | `account_id`, `market_id`, `status` | `Order[]` |
| `/orders/{order_id}` | None | `Order` belonging to this owner |
| `/fills` | `account_id`, `market_id` | `Fill[]` |
| `/ledger` | `account_id`, `kind` | `Entry[]` |
| `/funding-payments` | `account_id`, `market_id` | `Payment[]` |
| `/closeouts` | `account_id`, `market_id`, `kind` | `Event[]` |

The five history feeds and the orders list also take `from`, `to`, `limit`, `cursor`. Bounds are non-negative Unix milliseconds. Follow [Pagination](https://docs.aultblockchain.com/dex-api/getting-started/pagination.md); an empty array is a valid result. An invalid address/ID/filter returns 400, an order absent from this owner's history returns 404, and storage failures return 500.

`status` is `open`, `closed`, `canceled`. Ledger `kind` is `deposit`, `withdraw`, `collateral_moved`; closeout `kind` is `liquidation` or `adl`. The ledger has no `market_id` filter because collateral movement is account scoped.

## Amounts and signs

Account collateral/equity and ledger/payment amounts are human collateral units. Position quantity and order/fill quantities are human base units; position values and `quoteNotional` are human quote units. Preserve decimal strings.

* `pendingFundingPayment` on a position is positive when it **owes** funding and negative when it receives.
* Settled funding `amount` is positive when the account **receives** and negative when it pays. Its sign convention is the opposite of pending funding.
* `fee` and `feeDenom` on fills describe the indexed fee. Either can be null for historical rows without this information.
* Mark-dependent account/position fields can be null. This means the API cannot value the account, not that the account has zero risk.

## Order and strategy lifecycle

`filledQuantity`, `averageFillPrice` and `fillHistoryComplete` let a client check whether indexed fills reconcile with an order. `reduceOnly: null` means the flag is unknown. `timeInForce: "gtc"` is the backend's label for the resting path; inspect `deadline` for expiry.

A conditional parent exposes `conditional` and does not fill directly. After activation, follow `conditional.childOrderId`; the child carries `parentOrderId`. `links` records the [order-group edges](https://docs.aultblockchain.com/dex-api/rest/orders.md#order-links), including ended edges. A triggered parent is not proof of an executed exit.

A TWAP parent exposes `twap`; its `quantity` is total strategy size and its fills aggregate child slices. Its `accountId` is empty because routing is chosen per slice. A child uses `twapId` to identify its parent. Schedule fields can become null when the schedule is removed. Cancel the parent through the [supported transaction route](https://docs.aultblockchain.com/dex-api/trading/cancel-order.md#cancelling-a-twap-schedule), then reconcile the parent and fills.

```bash theme={null}
curl -fsS "$API_URL/api/v1/perp/owners/$OWNER/accounts"
curl -fsS --get "$API_URL/api/v1/perp/owners/$OWNER/orders" \
  --data-urlencode 'status=open' --data-urlencode "market_id=$MARKET_ID"
curl -fsS "$API_URL/api/v1/perp/owners/$OWNER/funding-payments?limit=100"
```

Join orders and fills by full `orderId`, accounts by `accountId`, and markets by `marketId`. REST
fill `quantity` is already a per-event human-base amount. Use this paginated feed for historical
accounting. For live updates, use [Perpetual Subscriptions](https://docs.aultblockchain.com/dex-api/websocket/perpetuals.md) and reconcile with REST.
Re-read orders after reconnect or an unknown transaction outcome. A history response shows indexed data. It does not confirm that an order was submitted, and it is not a single point-in-time copy of the account.

## Response field reference

Types below describe JSON, not numeric units. See the unit notes above. Nullable values must not be replaced with zero.

> [accordion] Account
>
> | Field | JSON type |
> | - | - |
> | `accountId` | string |
> | `marginMode` | string |
> | `isolatedMarketId` | string or null |
> | `collateral` | string |
> | `equity` | string or null |

> [accordion] Position
>
> | Field | JSON type |
> | - | - |
> | `accountId` | string |
> | `marketId` | string |
> | `marginMode` | string |
> | `side` | string |
> | `quantity` | string |
> | `entryPrice` | string |
> | `markPrice` | string or null |
> | `notional` | string or null |
> | `leverage` | number |
> | `unrealizedPnl` | string or null |
> | `pendingFundingPayment` | string or null |
> | `initialMargin` | string or null |
> | `maintenanceMargin` | string or null |

> [accordion] MarginConfig
>
> | Field | JSON type |
> | - | - |
> | `marketId` | string |
> | `marginMode` | string |
> | `leverage` | number |

> [accordion] Order
>
> | Field | JSON type |
> | - | - |
> | `orderId` | string |
> | `cloid` | string or null |
> | `accountId` | string |
> | `marketId` | string |
> | `side` | string |
> | `timeInForce` | string |
> | `price` | string |
> | `quantity` | string |
> | `openQuantity` | string |
> | `reduceOnly` | boolean or null |
> | `filledQuantity` | string |
> | `averageFillPrice` | string or null |
> | `status` | string |
> | `closeReason` | string or null |
> | `createdAt` | number |
> | `deadline` | number or null |
> | `fillHistoryComplete` | boolean |
> | `parentOrderId` | string or null |
> | `conditional` | Conditional or null |
> | `links` | array of Link |
> | `twapId` | string or null |
> | `twap` | Twap or null |

> [accordion] Twap
>
> | Field | JSON type |
> | - | - |
> | `startTime` | number |
> | `numSlices` | number |
> | `sliceIndex` | number or null |
> | `remainingSize` | string or null |
> | `nextCheck` | number or null |
> | `worstPrice` | string or null |
> | `priceTolerance` | string or null |

> [accordion] Conditional
>
> | Field | JSON type |
> | - | - |
> | `orderType` | string |
> | `triggerPrice` | string |
> | `triggerAbove` | boolean |
> | `state` | string |
> | `postOnly` | boolean |
> | `childOrderId` | string or null |
> | `triggeredAt` | number or null |
> | `activatedAt` | number or null |
> | `awaitingPrimary` | boolean |

> [accordion] Fill
>
> | Field | JSON type |
> | - | - |
> | `id` | string |
> | `timestamp` | number |
> | `accountId` | string |
> | `marketId` | string |
> | `orderId` | string |
> | `side` | string |
> | `liquidity` | string |
> | `price` | string |
> | `quantity` | string |
> | `quoteNotional` | string |
> | `fee` | string or null |
> | `feeDenom` | string or null |

> [accordion] Payment
>
> | Field | JSON type |
> | - | - |
> | `id` | string |
> | `timestamp` | number |
> | `accountId` | string |
> | `marketId` | string |
> | `amount` | string |

> [accordion] Entry
>
> | Field | JSON type |
> | - | - |
> | `id` | string |
> | `timestamp` | number |
> | `kind` | string |
> | `accountId` | string or null |
> | `fromAccountId` | string or null |
> | `toAccountId` | string or null |
> | `collateralDenom` | string or null |
> | `amount` | string |
> | `reason` | string or null |

> [accordion] Event
>
> | Field | JSON type |
> | - | - |
> | `id` | string |
> | `timestamp` | number |
> | `kind` | string |
> | `role` | string |
> | `accountId` | string or null |
> | `targetAccountId` | string or null |
> | `counterpartyAccountId` | string or null |
> | `marketId` | string or null |
> | `isLong` | boolean or null |
> | `equity` | string or null |
> | `maintenanceMargin` | string or null |
> | `orderId` | string or null |
> | `bankruptcyPrice` | string or null |
> | `markPrice` | string or null |
> | `quantity` | string or null |
> | `repaidDebt` | string or null |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.