---
title: "Track a position you prepared"
method: GET
path: "/v1/positions/{positionId}"
tags: ["positions"]
---

# Track a position you prepared

`GET /v1/positions/{positionId}`

## Request

- Base URL: `https://yield.trdefi.com`
- URL: `https://yield.trdefi.com/v1/positions/{positionId}`
- Auth: HTTP bearer

`positionId` is the `strategyHash` returned by `POST /v1/positions` — there is no second identifier to keep track of.

**We only report what we have observed.** `prepared` = nothing seen on-chain yet. `shipped` = the strategy is in the live catalogue, which means your wallet signed, broadcast and it was included. `filled` = it has settled volume.

**Two states we deliberately do not report.** There is no `signed`: a signature is unobservable before broadcast, and by then the position is `shipped`. There is no `failed`: we watch the catalogue, not every reverted transaction — your own receipt is the authority on that.

Timestamps are named `firstSeen*` because they record when **we** observed a state, not when it happened.

A key only ever sees positions it prepared itself. Another key's position and a non-existent one both return `404`, deliberately indistinguishable.

## Path parameters

- `positionId` string, required

## Response `200`

The observed lifecycle of your position

- PositionStatus
  - `data` object, required
    - `positionId` string, required: Same value as `strategyHash`. There is no second identifier.
    - `strategyHash` string, required
    - `status` 'prepared' | 'shipped' | 'filled', required: `prepared` — nothing observed on-chain yet. `shipped` — the strategy is in the live catalogue, so your wallet signed and broadcast it. `filled` — it has settled volume. `signed` and `failed` are deliberately absent: neither is observable by us without claiming knowledge we do not have.
    - `chain` string
    - `chainId` integer
    - `wallet` string
    - `tokenA` object
    - `tokenB` object
    - `makerFeeBps` integer, nullable
    - `protocolFeeBps` integer
    - `observedOnChain` boolean: True once we have seen the position in the live catalogue.
    - `volumeUsd` number, nullable
    - `preparedAt` string, date-time
    - `firstSeenOnChainAt` string, date-time, nullable: When **we** first observed it on-chain, not necessarily when it happened.
    - `firstSeenFilledAt` string, date-time, nullable
    - `signer` string: Always the client. This endpoint has never signed or broadcast anything.
  - `meta` Meta, required
    - `requestId` string, required
    - `generatedAt` string, date-time, required
    - `apiVersion` string, required
    - `freshnessSeconds` integer, nullable: How old the underlying roll-up is, in seconds. Null when not derived.
    - `cached` boolean: True when this response was served from our short-lived cache.

## Other responses

- `400`: Malformed or missing parameters
- `401`: Missing, malformed, revoked or out-of-scope key. The envelope never says which — a wrong key and a revoked key are indistinguishable.
- `404`: No such position — or it belongs to a different key. The two are deliberately indistinguishable.
- `429`: Rate limit exceeded. `Retry-After` is always present.

---

[API](https://skmtc.dev/trdefi/apis/trdefi-liquidity-api.md) · [All operations](https://skmtc.dev/trdefi/apis/trdefi-liquidity-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trdefi/apis/trdefi-liquidity-api/revisions/0175596aa1cb?raw)