(POST) Position State

POST /position_state/{start}/{size}

/position_state/{start}/{size}

Example Query:

https://www.perps-streaming.com/v1/8453a/0x8Ab178C07184ffD44F0ADfF4eA2ce6cFc33F3b86/position_state/0/10

This endpoint retrieves historical updates about a position's lifecycle across trading stages (e.g., RFQ, order placement, fills). The data it returns should be from the hedger's record of the quote within their system.

---

Request Parameters

• URL Path:

  • start: Pagination offset (0-indexed, e.g., 0 for first page).

  • size: Number of records.

• Body (JSON):

  • quote_id (required): Filter by specific quote ID (e.g., "99934").

Example Request

POST /position_state/0/10
Content-Type: application/json  
App-Name: Cloverfield  # Custom header for client identification  

{ "quote_id": "99934" }  

---

Response Fields

• count: Total number of matching records (across all pages).

• position_state[]: Array of updates, sorted by modify_time descending.

---

Example Response (Open and Close On-Chain)

position_state after an on-chain SendQuote:

{
    "count": 1,
    "position_state": [
        {
            "id": "130638",
            "quote_id": 130638,
            "filled_amount_open": 5.3,
            "avg_price_open": 2.0683410046027615,
            "filled_amount_close": 0,
            "avg_price_close": 0,
            "action_status": "success",
            "last_seen_action": "",
            "failure_type": "",
            "order_type": 0,
            "create_time": 1744798243000,
            "modify_time": 1744798261000,
            "counterparty_address": "0x1EcAbF0Eba136920677C9575FAccee36f30592cf",
            "error_code": "",
            "state_type": ""
        }
    ],
    "message": "Success"
}

position_state after an on-chain requestToCloseQuote:

{
    "count": 1,
    "position_state": [
        {
            "id": "130638",
            "quote_id": 130638,
            "filled_amount_open": 5.3,
            "avg_price_open": 2.0683410046027615,
            "filled_amount_close": 5.3,
            "avg_price_close": 2.0658604837097743,
            "action_status": "success",
            "last_seen_action": "",
            "failure_type": "",
            "order_type": 0,
            "create_time": 1744798243000,
            "modify_time": 1744798424474,
            "counterparty_address": "0x1EcAbF0Eba136920677C9575FAccee36f30592cf",
            "error_code": "",
            "state_type": ""
        }
    ],
    "message": "Success"
}

Data Sources

• On-Chain Contracts (getQuote):

  • quote_id, create_time (from createTimestamp), modify_time (from statusModifyTimestamp) and counterparty_address (partyA of the quote). These should match the data in the database about this quote.

• Hedger Databases:

  • All other fields (id, last_seen_action, action_status, state_type, etc.) from internal logs of order execution events. avg_price_open and avg_price_closed should reflect the prices at which the hedger filled the partyA.

---

Example Response (Instant Open and Close)

position_state after Instant Opening:

{
    "count": 1,
    "position_state": [
        {
            "id": "130637",
            "quote_id": 130637,
            "filled_amount_open": 5.3,
            "avg_price_open": 2.064838903342005,
            "filled_amount_close": 0,
            "avg_price_close": 0,
            "action_status": "success",
            "last_seen_action": "",
            "failure_type": "",
            "order_type": 0,
            "create_time": 1744797707000,
            "modify_time": 1744797719000,
            "counterparty_address": "0x1EcAbF0Eba136920677C9575FAccee36f30592cf",
            "error_code": "",
            "state_type": "",
            "temp_quote_id": -1744797705144139
        }
    ],
    "message": "Success"
}

position_state after Instant Closing:

{
    "count": 1,
    "position_state": [
        {
            "id": "130637",
            "quote_id": 130637,
            "filled_amount_open": 5.3,
            "avg_price_open": 2.064838903342005,
            "filled_amount_close": 5.3,
            "avg_price_close": 2.0671597041774934,
            "action_status": "success",
            "last_seen_action": "FillOrderInstantClose",
            "failure_type": "",
            "order_type": 0,
            "create_time": 1744797707000,
            "modify_time": 1744797847000,
            "counterparty_address": "0x1EcAbF0Eba136920677C9575FAccee36f30592cf",
            "error_code": "",
            "state_type": "",
            "temp_quote_id": -1744797705144139
        }
    ],
    "message": "Success"
}

Negative temp_quote_id values indicate instant trades (not standard quotes).