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

# Trading with the API

> Place and manage every order type available in the trading terminal.

The REST API uses the same order books, trading rules, fees, margin checks, and
paper execution engine as the trading terminal. Every create request requires
an `Idempotency-Key` header.

## Standard and advanced orders

Send orders to `POST /v1/orders`. If `type` is omitted, the request is treated
as a market order for compatibility with existing clients.

| `type`        | Required price fields                                     | Important options                              |
| ------------- | --------------------------------------------------------- | ---------------------------------------------- |
| `market`      | `expected_price`                                          | `slippage_tolerance_bps`, attached TP/SL       |
| `limit`       | `limit_price`                                             | attached TP/SL, IOC, FOK, or GTD time in force |
| `chase`       | `chase_offset`                                            | optional `chase_cap_price`                     |
| `stop_market` | `trigger_price`                                           | optional reduce-only protection                |
| `stop_limit`  | `trigger_price`, `limit_price`                            | opening conditional order                      |
| `take_market` | `trigger_price`                                           | opening conditional order                      |
| `take_limit`  | `trigger_price`, `limit_price`                            | opening conditional order                      |
| `take_profit` | `trigger_price`, `reduce_only: true`                      | position protection                            |
| `conditional` | `trigger_price`, `trigger_market_id`, `trigger_direction` | observe one market and execute on another      |

The server resolves provider, symbol, and venue coin from `market_id`. Do not
send those fields. `expected_price` records what your client observed, but it
never controls the execution price, margin calculation, or slippage reference.

## Limit order example

```bash theme={null}
curl https://developers.fundingperpetuals.com/v1/orders \
  -X POST \
  -H "Authorization: Bearer $FP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "limit",
    "account_id": "YOUR_ACCOUNT_ID",
    "market_id": "binance|BTCUSDT",
    "side": "buy",
    "size": 0.001,
    "limit_price": 115000,
    "leverage": 2,
    "margin_mode": "cross",
    "take_profit_price": 120000,
    "stop_loss_price": 112000
  }'
```

For a GTD limit, set `time_in_force` to `gtd` and provide
`gtd_expires_at` as a Unix timestamp in milliseconds. IOC and FOK limits use
`time_in_force` without an expiry.

## Manage working orders

Use `GET /v1/orders?account_id=...&status=working` for the complete bounded set
of pending and resting orders. This view is safer for reconciliation than
searching recent history.

If the server cannot prove the snapshot is complete inside the active-order
bound, it returns `503` with `Retry-After` instead of returning truncated data.

* `PATCH /v1/orders/{order_id}` changes price and optionally size.
* `PUT /v1/orders/{order_id}/attached-exits` sets or removes TP/SL attached to
  a resting limit entry. Send `null` to remove a leg.
* `DELETE /v1/orders/{order_id}` cancels a working order or queues cancellation
  when execution already owns the row.

Chase orders cannot be modified. Cancel the chase and place a replacement with
new offset or cap settings.

## Close and protect positions

`POST /v1/positions/{position_id}/close` derives the closing side, leverage,
margin mode, and reduce-only flag from the current position. It supports market,
limit, and external conditional closes. Omit `size` for a full close.

Use `PUT /v1/positions/{position_id}/exit-orders` to atomically place, modify,
and cancel multiple TP/SL levels. The request includes the position size and
current exit-order snapshot you observed. A concurrent position or order change
returns `409`, so fetch fresh state and rebuild the operation.

New TP and SL operations can reference each other by operation index to form an
OCO pair. When either leg fills, the other leg is canceled.

For an isolated position, `PUT /v1/positions/{position_id}/isolated-margin`
sets the desired total `extra_margin`. Repeating the same target is safe. A
reduction uses a fresh authoritative book and rejects when it would create
unsafe liquidation risk.

## TWAP and VWAP

Create both strategies with `POST /v1/twap-orders`. Set `strategy` to `twap`
or `vwap`, then provide the duration, slice interval, and optional randomized
timing. Optional trigger and termination prices use the same behavior as the
terminal.

The slice interval must be a whole number from 30 seconds through the smaller
of 12 hours or half the selected duration. Every schedule therefore has at
least two slices.

Read active schedules with `GET /v1/twap-orders?account_id=...`, inspect one
parent with `GET /v1/twap-orders/{id}`, and stop future slices with `DELETE` on
that resource. An in-flight child may still settle after cancellation begins.

## Scaled orders

Create a ladder with `POST /v1/scaled-orders`. Provide a start price, end
price, 2 to 10 rungs, and a `flat`, `ascending`, or `descending` distribution.
Every rung is an ordinary limit order and independently follows the platform's
fill and trading rules.

`GET /v1/scaled-orders/{id}` returns every rung's price, size, child order ID,
and placement rejection when applicable. `DELETE` fences unplaced rungs and
cancels every working child.

## Reconcile fills and closed positions

`GET /v1/fills?account_id=...` returns filled orders in settlement order with
fees, realized P\&L, notional, liquidity role, and partial-fill lineage. Use
`GET /v1/positions?account_id=...&status=closed` for cursor-paginated closed
position records.

Treat all cursors as opaque. Order and strategy state can continue changing
after a response, so reconcile by resource ID until it reaches a terminal
status.