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
Binance	Yes	Yes	Yes	Yes	Yes
Bybit	Yes	Yes	Yes	Yes	-
Gate.io	Yes	Yes	Yes	Yes	-
OKX	Yes	Yes	Yes	Yes	-
Hyperliquid	Yes	-	Yes	Yes	-

POST /oems/execution/leverage

Set leverage for a symbol on futures/perp markets.

Authentication

Requires valid Bearer token with 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

curl -X POST "https://api.renesis.fi/order-execution/execution/leverage" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "binance-perp-001",
    "symbol": "BTC/USDT:USDT",
    "leverage": 10
  }'

Response Example

{
  "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 /oems/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

curl "https://api.renesis.fi/order-execution/execution/leverage?exchange_account_id=binance-perp-001&symbol=BTC/USDT:USDT" \
  -H "Authorization: Bearer $TOKEN"

Response Example

{
  "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 /oems/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

curl -X POST "https://api.renesis.fi/order-execution/execution/margin-mode" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "binance-perp-001",
    "symbol": "BTC/USDT:USDT",
    "margin_mode": "isolated"
  }'

Response Example

{
  "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 /oems/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

curl "https://api.renesis.fi/order-execution/execution/positions?exchange_account_id=binance-perp-001" \
  -H "Authorization: Bearer $TOKEN"

Response Example

{
  "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 /oems/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

curl "https://api.renesis.fi/order-execution/execution/funding-history?exchange_account_id=binance-perp-001&symbol=BTC/USDT:USDT&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response Example

{
  "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 /oems/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

curl "https://api.renesis.fi/order-execution/execution/realized-pnl?exchange_account_id=binance-perp-001&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response Example

{
  "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 /oems/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

curl "https://api.renesis.fi/order-execution/execution/portfolio-margin/balance?exchange_account_id=binance-pm-001" \
  -H "Authorization: Bearer $TOKEN"

Response Example

{
  "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 /oems/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

curl "https://api.renesis.fi/order-execution/execution/portfolio-margin/account?exchange_account_id=binance-pm-001" \
  -H "Authorization: Bearer $TOKEN"

Response Example

{
  "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 /oems/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.

BNB in USDⓈ-M Futures Wallet will NOT be transferred.

Request Body (JSON)

exchange_account_id (string, required): The exchange account UUID (must be a Binance PM account)

Request Example

curl -X POST "https://api.renesis.fi/order-execution/execution/portfolio-margin/auto-collection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "binance-pm-001"
  }'

Response Example

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

POST /oems/execution/portfolio-margin/asset-collection

Trigger asset-specific collection for Portfolio Margin account. Transfers a specific asset from Futures Account to Margin account.

BNB transfer is NOT supported.

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

curl -X POST "https://api.renesis.fi/order-execution/execution/portfolio-margin/asset-collection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_account_id": "binance-pm-001",
    "asset": "USDT"
  }'

Response Example

{
  "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:

Have Portfolio Margin enabled on Binance (requires manual application)
Be registered in Renesis with portfolio_margin: true
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

Getting Started

API Reference

​Perps DMA API

​Key Features

​Supported Exchanges

​POST /oems/execution/leverage

​Authentication

​Request Body (JSON)

​Request Example

​Response Example

​GET /oems/execution/leverage

​Query Parameters

​Request Example

​Response Example

​POST /oems/execution/margin-mode

​Request Body (JSON)

​Request Example

​Response Example

​GET /oems/execution/positions

​Query Parameters

​Request Example

​Response Example

​GET /oems/execution/funding-history

​Query Parameters

​Request Example

​Response Example

​GET /oems/execution/realized-pnl

​Query Parameters

​Request Example

​Response Example

​Portfolio Margin Endpoints (Binance)

​GET /oems/execution/portfolio-margin/balance

​Query Parameters

​Request Example

​Response Example

​GET /oems/execution/portfolio-margin/account

​Query Parameters

​Request Example

​Response Example

​POST /oems/execution/portfolio-margin/auto-collection

​Request Body (JSON)

​Request Example

​Response Example

​POST /oems/execution/portfolio-margin/asset-collection

​Request Body (JSON)

​Request Example

​Response Example

​Portfolio Margin Notes

​What is Portfolio Margin?

​Key Concepts

​Setting Up Portfolio Margin

​PAPI Endpoints Used

Perps DMA API

Key Features

Supported Exchanges

POST /oems/execution/leverage

Authentication

Request Body (JSON)

Request Example

Response Example

GET /oems/execution/leverage

Query Parameters

Request Example

Response Example

POST /oems/execution/margin-mode

Request Body (JSON)

Request Example

Response Example

GET /oems/execution/positions

Query Parameters

Request Example

Response Example

GET /oems/execution/funding-history

Query Parameters

Request Example

Response Example

GET /oems/execution/realized-pnl

Query Parameters

Request Example

Response Example

Portfolio Margin Endpoints (Binance)

GET /oems/execution/portfolio-margin/balance

Query Parameters

Request Example

Response Example

GET /oems/execution/portfolio-margin/account

Query Parameters

Request Example

Response Example

POST /oems/execution/portfolio-margin/auto-collection

Request Body (JSON)

Request Example

Response Example

POST /oems/execution/portfolio-margin/asset-collection

Request Body (JSON)

Request Example

Response Example

Portfolio Margin Notes

What is Portfolio Margin?

Key Concepts

Setting Up Portfolio Margin

PAPI Endpoints Used