$PRIVY is live -

Skip to content
Docs

API reference

Positions

Every position across its lifecycle.

List positions

GET/api/v1/positionsAPI key

Returns positions across their whole lifecycle. Filter by status to list only open or closed positions.

Parameters

  • statusstring · queryoptional

    Only return positions in this status.

  • limitinteger · queryoptional

    Number of results, 1 to 100. Defaults to 25.

  • cursorstring · queryoptional

    Opaque cursor from a previous response’s pagination.nextCursor.

Response (array of)

  • idstring · uuid

    Position ID.

  • statusstring

    Position lifecycle status.

    pending_depositpending_fundingfundedopenclosingclosedfailedcancelledrefund_pendingrefundedrequires_review

  • mintstringnullable

    Token mint held by the position.

  • tokenobjectnullable

    Token metadata captured at buy time.

    • symbolstringnullable

      Ticker symbol.

    • namestringnullable

      Token name.

    • decimalsintegernullable

      Token decimals.

  • principalLamportsstring

    SOL principal the user deposited, in lamports.

  • costLamportsstringnullable

    SOL actually spent by the swap, in lamports.

  • boughtAmountstringnullable

    Raw token units received by the buy.

  • soldAmountstring

    Raw token units sold so far.

  • remainingAmountstringnullable

    Raw token units still held.

  • buyTradeIdstringnullable

    ID of the buy trade that opened the position.

  • buySignaturestringnullable

    Buy swap transaction signature.

  • openedAtstring · date-timenullable

    When the buy completed.

  • createdAtstring · date-time

    When the position was created.

  • updatedAtstring · date-time

    Last state change.

curl "https://privy.ac/api/v1/positions" \
  -H "X-API-Key: $PRIVY_API_KEY"

Try it

Sends a real request
Example response
{
  "data": [
    {
      "id": "4a3f2c1e-8b7d-4e6f-9a01-23456789abcd",
      "status": "open",
      "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
      "token": {
        "symbol": "Bonk",
        "name": "Bonk",
        "decimals": 5
      },
      "principalLamports": "50000000",
      "costLamports": "49852211",
      "boughtAmount": "161834512",
      "soldAmount": "0",
      "remainingAmount": "161834512",
      "buyTradeId": "9c1d2e3f-4a5b-4c6d-8e7f-0123456789ab",
      "buySignature": "5h8Xb3...kQ2",
      "openedAt": "2026-10-09T18:22:41.000Z",
      "createdAt": "2026-10-09T18:21:58.000Z",
      "updatedAt": "2026-10-09T18:22:41.000Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  },
  "requestId": "req_8f3a2c91d4e6b07f"
}

Get a position

GET/api/v1/positions/{id}API key

Returns a single position. Positions owned by another account return 404.

Parameters

  • idstring · pathrequired

    Position ID.

Response

  • idstring · uuid

    Position ID.

  • statusstring

    Position lifecycle status.

    pending_depositpending_fundingfundedopenclosingclosedfailedcancelledrefund_pendingrefundedrequires_review

  • mintstringnullable

    Token mint held by the position.

  • tokenobjectnullable

    Token metadata captured at buy time.

    • symbolstringnullable

      Ticker symbol.

    • namestringnullable

      Token name.

    • decimalsintegernullable

      Token decimals.

  • principalLamportsstring

    SOL principal the user deposited, in lamports.

  • costLamportsstringnullable

    SOL actually spent by the swap, in lamports.

  • boughtAmountstringnullable

    Raw token units received by the buy.

  • soldAmountstring

    Raw token units sold so far.

  • remainingAmountstringnullable

    Raw token units still held.

  • buyTradeIdstringnullable

    ID of the buy trade that opened the position.

  • buySignaturestringnullable

    Buy swap transaction signature.

  • openedAtstring · date-timenullable

    When the buy completed.

  • createdAtstring · date-time

    When the position was created.

  • updatedAtstring · date-time

    Last state change.

curl "https://privy.ac/api/v1/positions/4a3f2c1e-8b7d-4e6f-9a01-23456789abcd" \
  -H "X-API-Key: $PRIVY_API_KEY"

Try it

Sends a real request
Example response
{
  "data": {
    "id": "4a3f2c1e-8b7d-4e6f-9a01-23456789abcd",
    "status": "open",
    "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "token": {
      "symbol": "Bonk",
      "name": "Bonk",
      "decimals": 5
    },
    "principalLamports": "50000000",
    "costLamports": "49852211",
    "boughtAmount": "161834512",
    "soldAmount": "0",
    "remainingAmount": "161834512",
    "buyTradeId": "9c1d2e3f-4a5b-4c6d-8e7f-0123456789ab",
    "buySignature": "5h8Xb3...kQ2",
    "openedAt": "2026-10-09T18:22:41.000Z",
    "createdAt": "2026-10-09T18:21:58.000Z",
    "updatedAt": "2026-10-09T18:22:41.000Z"
  },
  "requestId": "req_8f3a2c91d4e6b07f"
}