Skip to content

Track positions and earnings

Positions are read live from chain — Meadow reports what the user's address actually holds, not an internal ledger.

Positions

curl "https://meadow.example.com/v1/positions?userAddress=0xUser…" \
  -H "api-key: $EDITH_API_KEY"

One entry per venue the address holds shares in: the venue, the share balance, and its current value in the underlying asset (shares × the venue's live exchange rate). A position appears as soon as its deposit order confirms and shrinks or disappears on withdrawal.

Earnings

curl "https://meadow.example.com/v1/earnings?userAddress=0xUser…" \
  -H "api-key: $EDITH_API_KEY"

Earnings compare current value against cost basis — what the user actually put in through Meadow:

earnings = current value − cost basis

The response aggregates across positions and includes the per-position breakdown. Realized earnings from withdrawals are accounted at exit.

Practical guidance

  • Polling cadence: yield accrues smoothly — every few minutes is plenty for a dashboard. Poll orders (not positions) when you're waiting on a settlement to land.
  • The chain is the authority. Because shares sit in the user's own address, you can always cross-check: the venue's share token balance of userAddress on any explorer must match what /v1/positions reports.
  • Deposits made outside Meadow into the same venues also appear in the share balance — cost basis only tracks Meadow-settled flows, so earnings figures assume Meadow is the entry path.