Data Objects Reference

This document provides detailed information about the data objects used in the Perpetuals SDK.

Core Data Objects

Order

The primary data object representing a trading order in the perpetuals platform.

Fields

Field	Type	Description
`order_id`	int32	Unique identifier for the order
`owner`	string	The owner identifier for the order
`timestamp`	string	Order creation timestamp (ISO 8601 format)
`market_id`	int32	Identifier for the trading market
`market`	string	Human-readable market name (e.g., “BTC-PERP”)
`type`	OrderType	Type of order (MARKET, LIMIT, etc.)
`side`	Side	Order side (LONG or SHORT)
`threshold_price`	float	Price threshold for order execution
`size`	float	Order size/quantity
`leverage`	int32	Leverage multiplier
`status`	OrderStatus	Current order status
`filled_size`	float	Amount of the order that has been filled
`reduce_only`	bool	Whether this is a reduce-only order

Example

from forte_perpetuals_sdk.generated.base_objects.v1.order_pb2 import (
    Order, OrderType, Side, OrderStatus
)

# Create a sample order
order = Order(
    order_id=789,
    owner="trader_123",
    timestamp="2024-11-07T12:00:00Z",
    market_id=1,
    market="BTC-PERP",
    type=OrderType.ORDER_TYPE_MARKET,
    side=Side.SIDE_LONG,
    threshold_price=75000.0,
    size=0.5,
    leverage=10,
    status=OrderStatus.ORDER_STATUS_PENDING,
    filled_size=0.0,
    reduce_only=False
)

Position

The data object representing an open trading position in the perpetuals platform.

Fields

Field	Type	Description
`owner`	string	The owner identifier for the position
`market_id`	int32	Identifier for the trading market
`market`	string	Human-readable market name (e.g., “BTC-PERP”)
`side`	Side	Position side (LONG or SHORT)
`size`	float	Position size/quantity
`leverage`	int32	Leverage multiplier for the position
`entry_price`	float	Average entry price for the position
`mark_price`	float	Current mark price for the position
`unrealized_pnl`	float	Unrealized profit and loss
`realized_pnl`	float	Realized profit and loss
`margin_type`	MarginType	Type of margin (CROSS or ISOLATED)
`margin_amount`	float	Amount of margin allocated to the position
`liquidation_price`	float	Price at which position would be liquidated
`timestamp`	string	Position creation/update timestamp (ISO 8601 format)

Example

from forte_perpetuals_sdk.generated.base_objects.v1.position_pb2 import Position
from forte_perpetuals_sdk.generated.base_objects.v1.enums_pb2 import Side, MarginType

# Create a sample position
position = Position(
    owner="trader_123",
    market_id=1,
    market="BTC-PERP",
    side=Side.SIDE_LONG,
    size=0.5,
    leverage=10,
    entry_price=75000.0,
    mark_price=76000.0,
    unrealized_pnl=500.0,
    realized_pnl=0.0,
    margin_type=MarginType.MARGIN_TYPE_CROSS,
    margin_amount=3750.0,
    liquidation_price=68000.0,
    timestamp="2024-11-07T12:00:00Z"
)

GetOrderRequest

Request object for retrieving order information.

Fields

Field	Type	Description
`order_id`	int32	The unique order identifier to retrieve
`market_id`	int32	The market identifier where the order exists
`reduce_only`	bool	Filter for reduce-only orders

Example

from forte_perpetuals_sdk.generated.get_order.v1.get_order_pb2 import GetOrderRequest

request = GetOrderRequest(
    order_id=123,
    market_id=1,
    reduce_only=False
)

GetOrderResponse

Response object containing order information.

Fields

Field	Type	Description
`order`	Order	The requested order object

Example

from forte_perpetuals_sdk.generated.get_order.v1.get_order_pb2 import GetOrderResponse

# Response would be received from API call
response = GetOrderResponse(
    order=order  # Order object as defined above
)

GetOrdersRequest

Request object for retrieving multiple orders with filtering options.

Fields

Field	Type	Description
`owner`	string	Filter orders by owner identifier
`market_id`	int32	Filter orders by market identifier
`side`	Side	Filter orders by side (optional)
`status`	OrderStatus	Filter orders by status (optional)
`limit`	int32	Maximum number of orders to return

Example

from forte_perpetuals_sdk.generated.get_orders.v1.get_orders_pb2 import GetOrdersRequest
from forte_perpetuals_sdk.generated.base_objects.v1.enums_pb2 import Side

request = GetOrdersRequest(
    owner="trader_123",
    market_id=1,
    side=Side.SIDE_LONG,
    limit=50
)

GetOrdersResponse

Response object containing multiple orders.

Fields

Field	Type	Description
`orders`	repeated Order	List of order objects matching the request criteria

Example

from forte_perpetuals_sdk.generated.get_orders.v1.get_orders_pb2 import GetOrdersResponse

# Response would be received from API call
response = GetOrdersResponse(
    orders=[order1, order2, order3]  # List of Order objects
)

GetOpenPositionsRequest

Request object for retrieving open positions with filtering options.

Fields

Field	Type	Description
`owner`	string	Filter positions by owner identifier
`market_id`	int32	Filter positions by market identifier (optional)
`side`	Side	Filter positions by side (optional)

Example

from forte_perpetuals_sdk.generated.get_open_positions.v1.get_open_positions_pb2 import GetOpenPositionsRequest
from forte_perpetuals_sdk.generated.base_objects.v1.enums_pb2 import Side

request = GetOpenPositionsRequest(
    owner="trader_123",
    market_id=1,
    side=Side.SIDE_LONG
)

GetOpenPositionsResponse

Response object containing open positions.

Fields

Field	Type	Description
`positions`	repeated Position	List of position objects matching the request criteria

Example

from forte_perpetuals_sdk.generated.get_open_positions.v1.get_open_positions_pb2 import GetOpenPositionsResponse

# Response would be received from API call
response = GetOpenPositionsResponse(
    positions=[position1, position2]  # List of Position objects
)

Enums

OrderType

Defines the type of order being placed.

Value	Description
`ORDER_TYPE_MARKET`	Market order - executes immediately at current market price

Side

Defines the direction of the order.

Value	Description
`SIDE_LONG`	Long position - betting price will go up
`SIDE_SHORT`	Short position - betting price will go down

OrderStatus

Defines the current status of an order.

Value	Description
`ORDER_STATUS_PENDING`	Order has been submitted but not yet processed
`ORDER_STATUS_PARTIALLY_FILLED`	Order has been partially executed
`ORDER_STATUS_FULLY_FILLED`	Order has been completely executed
`ORDER_STATUS_CLOSED`	Order has been closed
`ORDER_STATUS_CANCELLED`	Order has been cancelled

TimeInForce

Defines how long an order remains active.

Value	Description
`TIME_IN_FORCE_GTC`	Good Till Cancelled - order remains active until filled or cancelled

MarginType

Defines the type of margin used for a position.

Value	Description
`MARGIN_TYPE_CROSS`	Cross margin - uses entire account balance as collateral
`MARGIN_TYPE_ISOLATED`	Isolated margin - uses only allocated margin as collateral

Working with Data Objects

Converting to Python Dictionaries

Use the utility functions to convert protobuf objects to Python dictionaries:

from forte_perpetuals_sdk.utils import order_to_dict, position_to_dict

# Convert order to dictionary with human-readable enum values
order_dict = order_to_dict(order)
print(order_dict['status'])  # Prints "FULLY_FILLED" instead of enum number

# Convert position to dictionary with human-readable enum values
position_dict = position_to_dict(position)
print(position_dict['margin_type'])  # Prints "CROSS" instead of enum number

Enum Conversions

The SDK provides utility enums that can convert from protobuf enum values:

from forte_perpetuals_sdk.utils import OrderType, Side, OrderStatus, MarginType
from forte_perpetuals_sdk.generated.base_objects.v1.enums_pb2 import (
    OrderType as ProtoOrderType,
    Side as ProtoSide,
    OrderStatus as ProtoOrderStatus,
    MarginType as ProtoMarginType
)

# Convert from protobuf enum to Python enum
order_type = OrderType.from_proto(ProtoOrderType.ORDER_TYPE_MARKET)
side = Side.from_proto(ProtoSide.SIDE_LONG)
status = OrderStatus.from_proto(ProtoOrderStatus.ORDER_STATUS_PENDING)
margin_type = MarginType.from_proto(ProtoMarginType.MARGIN_TYPE_CROSS)

print(order_type.value)   # Prints "MARKET"
print(side.value)         # Prints "LONG"
print(status.value)       # Prints "PENDING"
print(margin_type.value)  # Prints "CROSS"

Formatting for Display

Use the formatting utilities for human-readable summaries:

from forte_perpetuals_sdk.utils import format_order_summary, format_position_summary

# Format order summary
order_summary = format_order_summary(order)
print(order_summary)
# Output: "Order #789 (BTC-PERP): LONG 0.5 @ $75,000.00 - Status: PENDING"

# Format position summary
position_summary = format_position_summary(position)
print(position_summary)
# Output: "Position (BTC-PERP): LONG 0.5 @ $75,000.00, PnL: +$500.00 (CROSS margin)"

Type Safety

All data objects are fully typed for use with mypy and other type checkers:

from typing import Optional, List
from forte_perpetuals_sdk.generated.base_objects.v1.order_pb2 import Order
from forte_perpetuals_sdk.generated.base_objects.v1.position_pb2 import Position
from forte_perpetuals_sdk.generated.base_objects.v1.enums_pb2 import OrderStatus

def process_order(order: Order) -> Optional[float]:
    """Process an order and return the total value."""
    if order.status == OrderStatus.ORDER_STATUS_FULLY_FILLED:
        return order.size * order.threshold_price
    return None

def calculate_portfolio_pnl(positions: List[Position]) -> float:
    """Calculate total unrealized PnL across all positions."""
    return sum(position.unrealized_pnl for position in positions)

Best Practices

Always validate data: Check that required fields are set before using order or position objects
Use enums for comparisons: Compare against enum values rather than raw integers
Handle partial fills: Check filled_size vs size for partially filled orders
Monitor position health: Regularly check liquidation_price and unrealized_pnl for risk management
Timestamp handling: Parse timestamps as needed for your timezone requirements
Error handling: Always wrap API calls in try-catch blocks for robust error handling
Margin management: Understand the difference between CROSS and ISOLATED margin types
Batch operations: Use get_orders() and get_open_positions() for efficient bulk data retrieval

Protobuf Details

The data objects are generated from protobuf definitions located in the proto/ submodule. When the protobuf definitions are updated:

Run git submodule update --remote to get the latest definitions
Run buf generate to regenerate the Python classes
Update any custom wrapper code if field names or types change

The generated protobuf classes provide:

Serialization to/from binary protobuf format
JSON serialization support
Field validation and type checking
Default values for optional fields

Developer Docs

API Reference

SDK Reference

​Core Data Objects

​Order

​Fields

​Example

​Position

​Fields

​Example

​GetOrderRequest

​Fields

​Example

​GetOrderResponse

​Fields

​Example

​GetOrdersRequest

​Fields

​Example

​GetOrdersResponse

​Fields

​Example

​GetOpenPositionsRequest

​Fields

​Example

​GetOpenPositionsResponse

​Fields

​Example

​Enums

​OrderType

​Side

​OrderStatus

​TimeInForce

​MarginType

​Working with Data Objects

​Converting to Python Dictionaries

​Enum Conversions

​Formatting for Display

​Type Safety

​Best Practices

​Protobuf Details

Core Data Objects

Order

Fields

Example

Position

Fields

Example

GetOrderRequest

Fields

Example

GetOrderResponse

Fields

Example

GetOrdersRequest

Fields

Example

GetOrdersResponse

Fields

Example

GetOpenPositionsRequest

Fields

Example

GetOpenPositionsResponse

Fields

Example

Enums

OrderType

Side

OrderStatus

TimeInForce

MarginType

Working with Data Objects

Converting to Python Dictionaries

Enum Conversions

Formatting for Display

Type Safety

Best Practices

Protobuf Details