Docs
Launch App

List positions

GET
/v0/midnight/users/{user-address}/positions

Cursor-paginated list of a user's current Midnight positions.

Position type. type is lend for positions with credit, borrow for positions with debt, or collateral_only for positions with no credit or debt but remaining collateral. Closed positions with no credit, no debt, and no remaining collateral are excluded.

Performance fields. cost_basis uses the average cost method and is returned as a WAD-scaled bigint string in loan-token units. effective_rate_wad is a WAD-scaled annualized effective rate. Either field can be null when there is not enough attributable history.

Filters. chain_ids is required when loan_assets is provided. Range filters exist on created_at, credit, debt, cost_basis, and effective_rate_wad. active_only=true excludes matured markets. listed=true keeps only positions on listed markets; listed=false keeps only positions on unlisted markets.

Pagination. Response envelope: { cursor, data }. Positions are ordered newest-first by created_at by default.

Cache. public, max-age=2, stale-while-revalidate=1.

Path Parameters

user-address*string

User address to list positions for. Lowercase input is checksummed.

Query Parameters

chain_ids?array<>

Filter by chain ids. Supported chains: Ethereum (1) and Base (8453). Required when loan_assets is provided.

Itemsitems <= 100
market_ids?array<string>

Filter by Midnight market ids.

Itemsitems <= 100
types?array<>

Filter by position type.

Itemsitems <= 100
loan_assets?array<string>

Filter by loan token addresses. Combine with chain_ids; lowercase input is checksummed.

Itemsitems <= 100
maturities?array<|>

Filter by exact maturity timestamps, in unix seconds.

Itemsitems <= 100
active_only?string

When true, keep only positions whose market has not matured yet.

Value in

  • "true"
  • "false"
maturity_gte?|

Filter for maturities greater than or equal to this unix timestamp.

maturity_lte?|

Filter for maturities less than or equal to this unix timestamp.

credit_gte?string

Filter for credit greater than or equal to this value.

Match^\d{1,78}$
credit_lte?string

Filter for credit less than or equal to this value.

Match^\d{1,78}$
pending_fee_gte?string

Filter for pending fee greater than or equal to this value.

Match^\d{1,78}$
pending_fee_lte?string

Filter for pending fee less than or equal to this value.

Match^\d{1,78}$
debt_gte?string

Filter for debt greater than or equal to this value.

Match^\d{1,78}$
debt_lte?string

Filter for debt less than or equal to this value.

Match^\d{1,78}$
cost_basis_gte?string

Filter for cost basis greater than or equal to this value.

Match^\d{1,78}$
cost_basis_lte?string

Filter for cost basis less than or equal to this value.

Match^\d{1,78}$
effective_rate_wad_gte?string

Filter for effective rate WAD greater than or equal to this value.

Match^-?\d{1,78}$
effective_rate_wad_lte?string

Filter for effective rate WAD less than or equal to this value.

Match^-?\d{1,78}$
created_at_gte?|

Filter for position created_at greater than or equal to this unix timestamp.

created_at_lte?|

Filter for position created_at less than or equal to this unix timestamp.

sort_by?string

Sort field for cursor pagination.

Default"created_at"

Value in

  • "created_at"
  • "credit"
  • "debt"
  • "maturity"
  • "cost_basis"
  • "effective_rate_wad"
sort_direction?string

Sort direction for cursor pagination.

Default"desc"

Value in

  • "asc"
  • "desc"
limit?integer

Maximum number of items to return.

Range1 <= value <= 100
Default100
cursor?string

Opaque cursor from a previous page response.

Length1 <= length <= 4096
market_family_ids?array<string>

Filter by Midnight market family ids. Combined with market_ids using AND semantics.

Itemsitems <= 100
listed?string

Filter by market listing status. When true, returns only positions on listed markets; when false, only positions on unlisted markets. Omit to return both.

Value in

  • "true"
  • "false"

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v0/midnight/users/0xd4F43105098845fFE89B16E7A3DCdd0A31898118/positions"
{  "cursor": null,  "data": [    {      "chain_id": 8453,      "market_id": "0x56b822d7d8be6bded8e1782277989fe5dc4e5b0a4f7f9d349482bc933bd5436c",      "user_address": "0xd4F43105098845fFE89B16E7A3DCdd0A31898118",      "loan_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",      "maturity": 1786147200,      "created_at": 1783584485,      "type": "lend",      "credit": "1691361",      "pending_fee": "0",      "last_loss_factor": "0",      "loss_factor": "0",      "debt": "0",      "cost_basis": "1684382000000000000000000",      "effective_rate_wad": "51269234716454728",      "collaterals": []    },    {      "chain_id": 8453,      "market_id": "0xcc9418ea594c6e658650aedd205ce4544b266b69493f56fd2adc65c14bd06738",      "user_address": "0xd4F43105098845fFE89B16E7A3DCdd0A31898118",      "loan_token": "0x4200000000000000000000000000000000000006",      "maturity": 1784300400,      "type": "borrow",      "credit": "0",      "pending_fee": "0",      "last_loss_factor": "0",      "loss_factor": "0",      "debt": "1046492040981691",      "collaterals": [        {          "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",          "amount": "4000000"        }      ],      "created_at": 1783546093,      "cost_basis": "1046483736229728000000000000000000",      "effective_rate_wad": "327402597840809"    }  ]}

{  "error": {    "code": "VALIDATION_FAILED",    "message": "Validation failed",    "details": [      {        "code": "invalid_type",        "message": "Expected number, received string",        "path": [          "chain_ids",          0        ]      }    ],    "request_id": "f0e1d2c3-b4a5-4968-8728-1c0d1e2f3a4b"  }}

{  "error": {    "code": "INTERNAL_ERROR",    "message": "Internal server error",    "details": null,    "request_id": "f0e1d2c3-b4a5-4968-8728-1c0d1e2f3a4b"  }}

GETGet market state

Previous Page

GETList market positions

Next Page