POST Position State

/position-state

position-state/{start}/{size}

Example Query:

https://base-hedger82.rasa.capital/position-state/{start}/{size}

Overview

This endpoint gives insights into historical lifecycle updates for positions based on a quote ID or counterparty address. Results are sourced from the Notifications, Positions, and Symbol tables, then mapped into the response schema.

Endpoint Specification

URL: https://base-hedger82.rasa.capital/position-state/{start}/{size} Method: POST

Headers

  • Content-Type: application/json

  • Optional: App-Name:(client identifier)

cURL Example (Limit Open — Reserved but not yet Opened)

curl -X POST "https://base-hedger82.rasa.capital/position-state/0/10" \
     -H "Content-Type: application/json" \
     -H "App-Name: Cloverfield" \
     -d '{"quote_id": "131388"}'

Response (HTTP 200):

{
    "count": 1,
    "position_state": [
        {
            "id": "7d0c10a4-1d7e-44b9-8712-77c863bfab55",
            "create_time": 1745970777,
            "modify_time": 1745970777,
            "quote_id": 131388,
            "temp_quote_id": null,
            "counterparty_address": "0xEb42F3b1aC3b1552138C7D30E9f4e0eF43229542",
            "filled_amount_open": "0",
            "filled_amount_close": "0",
            "avg_price_open": "0",
            "avg_price_close": "0",
            "last_seen_action": "SendQuote",
            "action_status": "seen",
            "failure_type": null,
            "error_code": 0,
            "order_type": 0,
            "state_type": "alert"
        }
    ]
}

Path Parameters

Name
Type
Description

start

integer

0-based pagination offset

size

integer

Number of records to return (max 100)

Body Parameters (JSON)

Provide at least quote_id or address of the following to filter results; other fields are optional:

Field

Type

Description

quote_id

string

Exact quote ID (string). One of quote_id or address is required.

address

string

Counterparty address (Ethereum hex string). One of quote_id or address is required.

symbols

string[]

Optional filter by trading symbols (e.g., ["ETHUSD"]).

states

string[]

Optional filter by position state enums (e.g., ["alert"]).

create_time_gte

integer

Optional: include records with Notifications.create_time >= epoch seconds UTC.

modify_time_gte

integer

Optional: include records with Notifications.modify_time >= epoch seconds UTC.

Request & Response Schemas

Define Schemas

Create PositionsStateRequestSchema and PositionStateResponseSchema + PositionsStateOutputSchema in the schema file.

class PositionStateResponseSchema(BaseModel):
    id: UUID
    create_time: int
    modify_time: int
    quote_id: int
    temp_quote_id: Optional[int] = None
    counterparty_address: str
    filled_amount_open: Decimal = 0
    filled_amount_close: Decimal = 0
    avg_price_open: Decimal = 0
    avg_price_close: Decimal = 0
    last_seen_action: str
    action_status: str
    failure_type: Optional[str] = None
    error_code: Optional[int] = None
    order_type: int
    state_type: PositionStateType

class PositionsStateOutputSchema(BaseModel):
    count: int
    position_state: List[PositionStateResponseSchema]

Data Sources & Field Mapping

Response Field
Source Table.Column(s)
Notes

id

Notifications.id

Primary key (UUID) -> in some solver implementations this is also the quote ID.

create_time

Notifications.create_time

Epoch seconds UTC

modify_time

Notifications.modify_time

Epoch seconds UTC

quote_id

Notifications.quote_id

quote_id.

temp_quote_id

Notifications.temp_quote_id

Used for instant trades or null.

counterparty_address

Notifications.counterparty_address

partyA address

filled_amount_open

Notifications.filled_amount_open

Recorded open fill amount

avg_price_open

Notifications.avg_price_open

Recorded open fill price

filled_amount_close

Notifications.filled_amount_close

Recorded close fill amount

avg_price_close

Notifications.avg_price_close

Recorded close fill price

last_seen_action

Notifications.last_seen_action

e.g., SendQuote, FillLimitOrderOpen

action_status

Notifications.action_status

success, seen, etc.

failure_type

Notifications.failure_type

If action failed

error_code

Notifications.error_code

Numeric code

order_type

Notifications.order_type

Limit = 0, Market = 1

state_type

Notifications.state_type

"alert" or "report"

Implementation Details (Annotated)

This section explains how each piece fits together.

Router Layer (routers.py)

@common_router.post(
    '/position-state/{start}/{size}',
    responses={status.HTTP_200_OK: {"model": PositionsStateOutputSchema}},
    response_model=PositionsStateOutputSchema
)
@with_context_db_session
async def search_position_state(
    request: PositionsStateRequestSchema,
    start: NonNegativeInt = 0,
    size: PositiveInt = 100
):
    # Map incoming HTTP payload to internal search DTO
    new_request = NotificationsRequestSchema()
    new_request.counterparty_address = request.address
    new_request.quote_id = request.quote_id
    new_request.symbols = request.symbols
    new_request.states = request.states
    new_request.timestamp_gte = request.modify_time_gte

    # Call service layer to fetch and map results
    count, data = search_notification_by_counterparty(
        new_request, start, size, map_to_positions_state=True
    )

    # Return raw dict form; FastAPI serializes to schema
    return dict(count=count, position_state=data)

Controller Layer (controllers.py)

# Located in controllers.py
# Handles fetching and mapping notifications to position state

def search_notification_by_counterparty(
    request: NotificationsRequestSchema,
    start: int,
    size: int,
    map_to_positions_state: bool = False
):
    # a. Sanitize page size
    size = min(size, 100)

    # b. Handle relative timestamps (e.g., -3600 for last hour)
    if request.timestamp_gte and request.timestamp_gte < 0:
        request.timestamp_gte = get_now_epoch() + request.timestamp_gte

    # c. Build base SQLAlchemy query with necessary joins
    stmt = (
        Notifications.select()
        .outerjoin(
            Positions,
            or_(
                Positions.quote_id == Notifications.quote_id,
                Positions.temp_quote_id == Notifications.temp_quote_id
            )
        )
        .outerjoin(
            Symbol, Positions.symbol_id == Symbol.symbol_id
        )
        .where(Notifications.should_send == true())
    )

    # d. Apply filters based on request fields
    if request.quote_id:
        if is_quote_id_temp(request.quote_id):
            stmt = stmt.where(Notifications.temp_quote_id == request.quote_id)
        else:
            stmt = stmt.where(Notifications.quote_id == request.quote_id)
    if request.counterparty_address:
        stmt = stmt.where(
            Notifications.counterparty_address == request.counterparty_address
        )
    if request.states:
        stmt = stmt.where(Positions.state.in_(request.states))
    if request.symbols:
        stmt = stmt.where(Symbol.title.in_(request.symbols))
    if request.timestamp_gte:
        stmt = stmt.where(Notifications.create_time >= request.timestamp_gte)

    # e. Count and paginate
    count = session.count_star(stmt)
    records = (
        session.scalars_all(
            stmt.order_by(desc(Notifications.create_time))
                .offset(start)
                .limit(size)
        )
    )

    # f. Map to DTOs
    result = []
    for row in records:
        data = row.to_dict()
        if map_to_positions_state:
            result.append(map_notification_to_positions_state(data))
        else:
            result.append(prepare_notification_to_send(data))
    return count, result

Example (Full Open Position -> Close Position Flow)

cURL Query

curl -X POST "https://base-hedger82.rasa.capital/position-state/0/10" \
     -H "Content-Type: application/json" \
     -H "App-Name: Cloverfield" \
     -d '{"quote_id": "131391"}'

fResponse (HTTP 200):

{
    "count": 6,
    "position_state": [
        {
            "id": "000be762-2592-43b0-937f-32a75fa4587a", //last notification
            "create_time": 1745976098,
            "modify_time": 1745976098,
            "quote_id": 131391,
            "temp_quote_id": null,
            "counterparty_address": "0xEb42F3b1aC3b1552138C7D30E9f4e0eF43229542",
            "filled_amount_open": "0",
            "filled_amount_close": "0",
            "avg_price_open": "0",
            "avg_price_close": "0",
            "last_seen_action": "FillLimitOrderClose",
            "action_status": "success",
            "failure_type": null,
            "error_code": 0,
            "order_type": 0,
            "state_type": "alert"
        },
        {
            "id": "4763fe3d-e3ed-40f9-9821-2b501342579b",
            "create_time": 1745976092,
            "modify_time": 1745976092,
            "quote_id": 131391,
            "temp_quote_id": null,
            "counterparty_address": "0xEb42F3b1aC3b1552138C7D30E9f4e0eF43229542",
            "filled_amount_open": "0",
            "filled_amount_close": "6.70000000",
            "avg_price_open": "0",
            "avg_price_close": "2.2345",
            "last_seen_action": "RequestToClosePosition",
            "action_status": "success",
            "failure_type": null,
            "error_code": 0,
            "order_type": 0,
            "state_type": "report"
        },
        {
            "id": "c99b51b8-a18e-4271-af05-3ed37f3805b9",
            "create_time": 1745976091,
            "modify_time": 1745976091,
            "quote_id": 131391,
            "temp_quote_id": null,
            "counterparty_address": "0xEb42F3b1aC3b1552138C7D30E9f4e0eF43229542",
            "filled_amount_open": "0",
            "filled_amount_close": "0",
            "avg_price_open": "0",
            "avg_price_close": "0",
            "last_seen_action": "RequestToClosePosition",
            "action_status": "seen",
            "failure_type": null,
            "error_code": 0,
            "order_type": 0,
            "state_type": "alert"
        },
        {
            "id": "8ff29bbd-6ca6-42cd-973f-20b6f88bfdea",
            "create_time": 1745976010,
            "modify_time": 1745976010,
            "quote_id": 131391,
            "temp_quote_id": null,
            "counterparty_address": "0xEb42F3b1aC3b1552138C7D30E9f4e0eF43229542",
            "filled_amount_open": "0",
            "filled_amount_close": "0",
            "avg_price_open": "0",
            "avg_price_close": "0",
            "last_seen_action": "FillLimitOrderOpen",
            "action_status": "success",
            "failure_type": null,
            "error_code": 0,
            "order_type": 0,
            "state_type": "alert"
        },
        {
            "id": "98620b7c-c752-42ed-8611-34bde40a4b28",
            "create_time": 1745976004,
            "modify_time": 1745976004,
            "quote_id": 131391,
            "temp_quote_id": null,
            "counterparty_address": "0xEb42F3b1aC3b1552138C7D30E9f4e0eF43229542",
            "filled_amount_open": "6.70000000",
            "filled_amount_close": "0",
            "avg_price_open": "2.2367",
            "avg_price_close": "0",
            "last_seen_action": "SendQuote",
            "action_status": "success",
            "failure_type": null,
            "error_code": 0,
            "order_type": 0,
            "state_type": "report"
        },
        {
            "id": "2f383602-054e-46a2-96e6-b39a7c483c49", //first notification
            "create_time": 1745975999,
            "modify_time": 1745975999,
            "quote_id": 131391,
            "temp_quote_id": null,
            "counterparty_address": "0xEb42F3b1aC3b1552138C7D30E9f4e0eF43229542",
            "filled_amount_open": "0",
            "filled_amount_close": "0",
            "avg_price_open": "0",
            "avg_price_close": "0",
            "last_seen_action": "SendQuote",
            "action_status": "seen",
            "failure_type": null,
            "error_code": 0,
            "order_type": 0,
            "state_type": "alert"
        }
    ]
}

By Address

curl -X POST "https://base-hedger82.rasa.capital/position-state/0/50" \
     -H "Content-Type: application/json" \
     -H "App-Name: Cloverfield" \
     -d '{
       "address": "0x20F764F49bf8A2c653942dA29FeD1D7A7BAefD20"
     }'

Response (200 OK):

{
  "count": 383,
  "position_state": [ /* items */ ]
}

Full Lifecycle Flow

Below is the end-to-end sequence of events and how they map to the records you see in the /position-state response:

  1. RFQ Observed

    • On-Chain Event Poller listens for SendQuote events.

    • Creates a “alert” notification (state_type = "alert") with action_status = "seen" and zeros in all fill fields.

    • At this point the hedger can lock the quote. The quote is seen but not yet filled.

  2. Hedger Confirmation & Opening of the position

    • The hedger’s risk engine executes the quote on-chain.

    • Updates the Notificationstable with actual filled_amount_open and avg_price_open values.

    • Emits a “report” notification (state_type = "report") with action_status = "success" and real fill data.

  3. On-Chain Fill Event

    • Almost immediately thereafter, the contract itself emits an OpenPositionevent when the transaction finally lands on-chain.

    • Poller picks it up and creates another “alert” (state_type = "alert") with zeros in fill fields until the DB update completes.

    • The same poller picks up that on-chain event and writes a fresh Notification with

      • last_seen_action = "FillLimitOrderOpen"

      • action_status = "success"

PreviousGET Get Funding InfoNextSolver Flow Summary Example

Last updated