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

# Perps DMA API

> Direct Market Access API for perpetual futures trading

# Perps DMA API

The Perps DMA (Direct Market Access) API provides endpoints for managing perpetual futures positions, leverage, margin modes, and Portfolio Margin accounts.

## Key Features

* **Position Management**: View open positions across exchanges
* **Leverage Control**: Set and query leverage per symbol
* **Margin Mode**: Switch between cross and isolated margin
* **Funding History**: Track funding rate payments
* **Realized PnL**: View closed position profits/losses
* **Portfolio Margin**: Binance PM balance and collection endpoints

***

## Supported Exchanges

| Exchange        | Leverage | Margin Mode | Positions | Funding | Portfolio Margin | Notes                                                                                                             |
| --------------- | -------- | ----------- | --------- | ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Binance**     | Yes      | Yes         | Yes       | Yes     | Yes              |                                                                                                                   |
| **Bybit**       | Yes      | Yes         | Yes       | Yes     | -                | UTA single wallet                                                                                                 |
| **Gate.io**     | Yes      | Yes         | Yes       | Yes     | -                |                                                                                                                   |
| **OKX**         | Yes      | Yes         | Yes       | Yes     | -                | Unified account                                                                                                   |
| **Kraken**      | Yes      | Yes         | Yes       | Yes     | -                | Requires a separate **futures API key** (`futures.kraken.com`). See [Trading on Kraken](/oems-api/guides/kraken). |
| **Hyperliquid** | -        | -           | Yes       | -       | -                | Cross-margin only; no per-symbol leverage                                                                         |

***

## POST /order-execution/execution/leverage

Set leverage for a symbol on futures/perp markets.

### Authentication

Requires a valid API key whose user has the `trader` or `admin` role.

### Request Body (JSON)

* **exchange\_account\_id** (string, required): The exchange account UUID
* **symbol** (string, required): Trading pair in perp format (e.g., "BTC/USDT:USDT")
* **leverage** (number, required): Leverage value (e.g., 1, 5, 10, 20, 50, 100)
* **market\_type** (string, optional): `swap` or `future`. Default: `swap`

### Request Example

```bash theme={null}
curl -X POST "https://api.renesis.fi/order-execution/execution/leverage" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "binance-perp-001",
    "symbol": "BTC/USDT:USDT",
    "leverage": 10
  }'
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Leverage set to 10x for BTC/USDT:USDT",
  "statusCode": 200,
  "data": {
    "exchange": "binance",
    "exchange_account_id": "binance-perp-001",
    "symbol": "BTC/USDT:USDT",
    "leverage": 10,
    "result": { "leverage": 10, "symbol": "BTCUSDT" }
  }
}
```

***

## GET /order-execution/execution/leverage

Get current leverage and margin mode for a symbol.

### Query Parameters

* **exchange\_account\_id** (string, required): The exchange account UUID
* **symbol** (string, required): Trading pair (e.g., "BTC/USDT:USDT")
* **market\_type** (string, optional): `swap` or `future`. Default: `swap`

### Request Example

```bash theme={null}
curl "https://api.renesis.fi/order-execution/execution/leverage?exchange_account_id=binance-perp-001&symbol=BTC/USDT:USDT" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "exchange": "binance",
    "exchange_account_id": "binance-perp-001",
    "symbol": "BTC/USDT:USDT",
    "leverage": 10,
    "margin_mode": "cross",
    "position_side": "long",
    "position_size": 0.05,
    "notional": 4925.25,
    "unrealized_pnl": 125.50
  }
}
```

***

## POST /order-execution/execution/margin-mode

Set margin mode (cross or isolated) for a symbol.

### Request Body (JSON)

* **exchange\_account\_id** (string, required): The exchange account UUID
* **symbol** (string, required): Trading pair (e.g., "BTC/USDT:USDT")
* **margin\_mode** (string, required): `cross` or `isolated`
* **market\_type** (string, optional): `swap` or `future`. Default: `swap`

### Request Example

```bash theme={null}
curl -X POST "https://api.renesis.fi/order-execution/execution/margin-mode" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "binance-perp-001",
    "symbol": "BTC/USDT:USDT",
    "margin_mode": "isolated"
  }'
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Margin mode set to isolated for BTC/USDT:USDT",
  "statusCode": 200,
  "data": {
    "exchange": "binance",
    "exchange_account_id": "binance-perp-001",
    "symbol": "BTC/USDT:USDT",
    "margin_mode": "isolated",
    "result": {}
  }
}
```

***

## GET /order-execution/execution/positions

Fetch open positions from exchange (futures/perp only).

### Query Parameters

* **exchange\_account\_id** (string, required): The exchange account UUID
* **symbol** (string, optional): Filter by symbol
* **market\_type** (string, optional): `swap` or `future`. Default: `swap`

### Request Example

```bash theme={null}
curl "https://api.renesis.fi/order-execution/execution/positions?exchange_account_id=binance-perp-001" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "positions": [
      {
        "symbol": "BTC/USDT:USDT",
        "side": "long",
        "contracts": 0.05,
        "contract_size": 1,
        "entry_price": 98000.00,
        "mark_price": 98505.00,
        "notional": 4925.25,
        "leverage": 10,
        "unrealized_pnl": 25.25,
        "percentage": 0.51,
        "margin_mode": "cross",
        "liquidation_price": 88200.00,
        "collateral": 492.52,
        "timestamp": 1706745600000,
        "datetime": "2025-01-31T12:00:00Z",
        "exchange": "binance",
        "exchange_account_id": "binance-perp-001"
      }
    ],
    "count": 1
  }
}
```

***

## GET /order-execution/execution/funding-history

Fetch funding rate payments for perpetual futures.

### Query Parameters

* **exchange\_account\_id** (string, required): The exchange account UUID
* **symbol** (string, optional): Filter by symbol
* **since** (number, optional): Start timestamp in milliseconds
* **limit** (number, optional): Max number of records
* **market\_type** (string, optional): `swap` or `future`. Default: `swap`

### Request Example

```bash theme={null}
curl "https://api.renesis.fi/order-execution/execution/funding-history?exchange_account_id=binance-perp-001&symbol=BTC/USDT:USDT&limit=10" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "exchange": "binance",
    "exchange_account_id": "binance-perp-001",
    "symbol": "BTC/USDT:USDT",
    "payments": [
      {
        "id": "123456789",
        "symbol": "BTC/USDT:USDT",
        "amount": -0.15,
        "code": "USDT",
        "timestamp": 1706745600000,
        "datetime": "2025-01-31T12:00:00Z",
        "info": {}
      }
    ],
    "count": 1
  }
}
```

***

## GET /order-execution/execution/realized-pnl

Fetch realized PnL for perpetual futures positions.

### Query Parameters

* **exchange\_account\_id** (string, required): The exchange account UUID
* **symbol** (string, optional): Filter by symbol
* **since** (number, optional): Start timestamp in milliseconds
* **limit** (number, optional): Max number of records
* **market\_type** (string, optional): `swap` or `future`. Default: `swap`

### Request Example

```bash theme={null}
curl "https://api.renesis.fi/order-execution/execution/realized-pnl?exchange_account_id=binance-perp-001&limit=10" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "exchange": "binance",
    "exchange_account_id": "binance-perp-001",
    "symbol": null,
    "entries": [
      {
        "id": "987654321",
        "symbol": "BTC/USDT:USDT",
        "amount": 125.50,
        "code": "USDT",
        "timestamp": 1706745600000,
        "datetime": "2025-01-31T12:00:00Z",
        "info": {}
      }
    ],
    "count": 1
  }
}
```

***

# Portfolio Margin Endpoints (Binance)

Portfolio Margin is a unified margin system that combines cross margin, USDⓈ-M Futures, and COIN-M Futures into a single account with portfolio-based risk calculations.

***

## GET /order-execution/execution/portfolio-margin/balance

Get Portfolio Margin balance from Binance PAPI.

Returns detailed breakdown of:

* **Cross Margin**: Total, free, locked, borrowed, interest
* **USDⓈ-M Futures**: Wallet balance, unrealized PnL
* **COIN-M Futures**: Wallet balance, unrealized PnL

### Query Parameters

* **exchange\_account\_id** (string, required): The exchange account UUID (must be a Binance PM account)

### Request Example

```bash theme={null}
curl "https://api.renesis.fi/order-execution/execution/portfolio-margin/balance?exchange_account_id=binance-pm-001" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "exchange": "binance",
    "exchange_account_id": "binance-pm-001",
    "assets": {
      "USDT": {
        "cross_margin": {
          "total": 10000.00,
          "free": 8500.00,
          "locked": 1500.00,
          "borrowed": 0,
          "interest": 0
        },
        "um_futures": {
          "wallet": 2500.00,
          "unrealized_pnl": 125.50
        },
        "cm_futures": {
          "wallet": 0,
          "unrealized_pnl": 0
        },
        "total_wallet_balance": 12500.00,
        "negative_balance": 0
      },
      "BTC": {
        "cross_margin": {
          "total": 0.5,
          "free": 0.45,
          "locked": 0.05,
          "borrowed": 0,
          "interest": 0
        },
        "um_futures": {
          "wallet": 0,
          "unrealized_pnl": 0
        },
        "cm_futures": {
          "wallet": 0.1,
          "unrealized_pnl": 0.005
        },
        "total_wallet_balance": 0.6,
        "negative_balance": 0
      }
    }
  }
}
```

***

## GET /order-execution/execution/portfolio-margin/account

Get Portfolio Margin account info from Binance PAPI.

Returns raw PAPI balance and UM account data.

### Query Parameters

* **exchange\_account\_id** (string, required): The exchange account UUID (must be a Binance PM account)

### Request Example

```bash theme={null}
curl "https://api.renesis.fi/order-execution/execution/portfolio-margin/account?exchange_account_id=binance-pm-001" \
  -H "X-API-Key: $API_KEY"
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Success",
  "statusCode": 200,
  "data": {
    "exchange": "binance",
    "exchange_account_id": "binance-pm-001",
    "papi_balance": [
      {
        "asset": "USDT",
        "crossMarginAsset": "10000.00",
        "crossMarginFree": "8500.00",
        "crossMarginLocked": "1500.00",
        "umWalletBalance": "2500.00",
        "umUnrealizedPNL": "125.50",
        "cmWalletBalance": "0",
        "cmUnrealizedPNL": "0",
        "totalWalletBalance": "12500.00"
      }
    ],
    "papi_um_account": {
      "totalInitialMargin": "1000.00",
      "totalMaintMargin": "200.00",
      "totalWalletBalance": "12500.00",
      "totalUnrealizedProfit": "125.50",
      "totalMarginBalance": "12625.50",
      "availableBalance": "11500.00",
      "maxWithdrawAmount": "11500.00"
    }
  }
}
```

***

## POST /order-execution/execution/portfolio-margin/auto-collection

Trigger auto-collection for Portfolio Margin account.

Transfers **all positive balances** from USDⓈ-M and COIN-M Futures Wallets to Cross Margin Wallet.

<Warning>
  BNB in USDⓈ-M Futures Wallet will NOT be transferred.
</Warning>

### Request Body (JSON)

* **exchange\_account\_id** (string, required): The exchange account UUID (must be a Binance PM account)

### Request Example

```bash theme={null}
curl -X POST "https://api.renesis.fi/order-execution/execution/portfolio-margin/auto-collection" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "binance-pm-001"
  }'
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Auto-collection triggered successfully",
  "statusCode": 200,
  "data": {
    "success": true,
    "exchange": "binance",
    "exchange_account_id": "binance-pm-001",
    "response": {}
  }
}
```

***

## POST /order-execution/execution/portfolio-margin/asset-collection

Trigger asset-specific collection for Portfolio Margin account.

Transfers a **specific asset** from Futures Account to Margin account.

<Warning>
  BNB transfer is NOT supported.
</Warning>

### Request Body (JSON)

* **exchange\_account\_id** (string, required): The exchange account UUID (must be a Binance PM account)
* **asset** (string, required): Asset to transfer (e.g., "USDT", "BTC")

### Request Example

```bash theme={null}
curl -X POST "https://api.renesis.fi/order-execution/execution/portfolio-margin/asset-collection" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "binance-pm-001",
    "asset": "USDT"
  }'
```

### Response Example

```json theme={null}
{
  "isError": false,
  "message": "Asset-collection triggered for USDT",
  "statusCode": 200,
  "data": {
    "success": true,
    "exchange": "binance",
    "exchange_account_id": "binance-pm-001",
    "asset": "USDT",
    "response": {}
  }
}
```

***

## Portfolio Margin Notes

### What is Portfolio Margin?

Portfolio Margin is a margin system that calculates margin requirements based on the overall risk of your portfolio, rather than individual positions. This typically results in **lower margin requirements** compared to traditional isolated margin.

### Key Concepts

| Concept             | Description                                            |
| ------------------- | ------------------------------------------------------ |
| **Cross Margin**    | Shared margin pool across all positions                |
| **USDⓈ-M Futures**  | USD-margined perpetual/delivery contracts              |
| **COIN-M Futures**  | Coin-margined perpetual/delivery contracts             |
| **Auto-Collection** | Moves funds from Futures to Cross Margin automatically |
| **uniMMR**          | Unified Maintenance Margin Ratio across all accounts   |

### Setting Up Portfolio Margin

To use Portfolio Margin endpoints, your Binance account must:

1. Have Portfolio Margin enabled on Binance (requires manual application)
2. Be registered in Renesis with `portfolio_margin: true`
3. Meet Binance's minimum equity requirements (\$100,000+ in some regions)

### PAPI Endpoints Used

These endpoints call Binance's Portfolio Margin API (PAPI):

| Endpoint                             | PAPI Endpoint                  | Description             |
| ------------------------------------ | ------------------------------ | ----------------------- |
| `/portfolio-margin/balance`          | GET /papi/v1/balance           | Full balance breakdown  |
| `/portfolio-margin/account`          | GET /papi/v1/um/account        | UM account info         |
| `/portfolio-margin/auto-collection`  | POST /papi/v1/auto-collection  | Transfer all assets     |
| `/portfolio-margin/asset-collection` | POST /papi/v1/asset-collection | Transfer specific asset |