tapimo 0.9.0 → 0.10.0

package/src/apps/data/routes/balances.ts

@@ -66,7 +66,12 @@ export namespace schema {
         include: Schema.totalCountInclude,
         limit: Schema.Limit,
         page: Schema.Page,
-        'valuation.currency': Schema.Denomination,
+        'valuation.currency': Schema.Denomination.check(
+          z.describe(
+            'When present, include each holding’s nominal value in this denomination. ' +
+              'Case-insensitive and must be priced by the configured FX oracle.',
+          ),
+        ),
         verified: z
           .optional(Schema.booleanQuery())
           .check(
@@ -141,11 +146,11 @@ export namespace schema {
           ),
         token: Tokens.schema.Token,
         valuation: z
-          .nullable(Valuation.schema.Value)
+          .optional(z.nullable(Valuation.schema.Value))
           .check(
             z.describe(
-              'The holding’s nominal value in the requested `valuation.currency`, or `null` when the ' +
-                'token is unverified, its display currency has no rate, or rates were unavailable.',
+              'The holding’s nominal value when `valuation.currency` is requested, or `null` when ' +
+                'the token is unverified, its display currency has no rate, or rates were unavailable.',
             ),
           ),
       }),
@@ -198,7 +203,12 @@ export namespace schema {
     export const Query = z
       .strictObject({
         chainId: Schema.ChainIdQuery,
-        'valuation.currency': Schema.Denomination,
+        'valuation.currency': Schema.Denomination.check(
+          z.describe(
+            'When present, include the holding’s nominal value in this denomination. ' +
+              'Case-insensitive and must be priced by the configured FX oracle.',
+          ),
+        ),
       })
       .check(z.describe('Query parameters for reading one account token balance.'))
 
@@ -229,7 +239,7 @@ export function addresses(options: addresses.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form, and each verified holding carries its nominal value in the requested denomination.',
+          'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form. Pass `valuation.currency` to include nominal values.',
         operationId: 'getAddressBalances',
         responses: OpenApi.responses({
           errors: { 502: 'Could not read balance or token data from an upstream service.' },
@@ -269,26 +279,13 @@ export function addresses(options: addresses.Options = {}) {
           const verified = query.verified || query.currency !== undefined
           const feeEligible = query.feeEligible ?? false
 
-          // The fee-token set powers both the per-row `feeEligible` flag (always)
-          // and the optional `feeEligible=true` page restriction. It is memoized
-          // per chain (a near-constant), so one read feeds the page, the count,
-          // and the row enrichment. It is a best-effort enrichment: a lookup
-          // failure omits `feeEligible` rather than failing the page — unless the
-          // caller explicitly asked to filter by `feeEligible`, where the filter
-          // can't be honored, so the failure surfaces as the declared `502`.
-          const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch((cause) => {
-            if (feeEligible) throw cause
-            return undefined
-          })
-
           const balances = await getAddressBalances(c, {
             address,
             chainId,
             currency: query.currency,
             cursor: query.cursor,
-            denomination: query['valuation.currency'] ?? 'USD',
+            denomination: query['valuation.currency'],
             feeEligible,
-            feeTokens,
             includeTotalCount: query.include.includes('totalCount'),
             limit: query.limit,
             oracle,
@@ -356,10 +353,28 @@ export function addresses(options: addresses.Options = {}) {
         const { address, token } = c.req.valid('param')
         const query = c.req.valid('query')
         const chainId = query.chainId ?? c.get('chainId')
+        const denomination = query['valuation.currency']
 
         try {
-          const snapshot = await VerifiedTokens.snapshot(c, chainId)
-          const [balance, resolvedToken] = await Promise.all([
+          const rates = denomination
+            ? await Valuation.rateSet(c, oracle)
+                .then((rates) => {
+                  if (denomination !== rates.base && rates.rates[denomination] === undefined)
+                    throw new Valuation.UnsupportedDenominationError(denomination, oracle.name)
+                  return rates
+                })
+                .catch((cause) => {
+                  if (cause instanceof Valuation.UnsupportedDenominationError) throw cause
+                  return undefined
+                })
+            : undefined
+          const snapshotPromise = VerifiedTokens.snapshot(c, chainId)
+          const resolvedTokenPromise = snapshotPromise.then((snapshot) =>
+            Timing.time(c, 'token', () =>
+              Tokens.resolveToken(c, { address: token, chainId, include: [], snapshot }),
+            ),
+          )
+          const [balance, feeTokens, snapshot, resolvedToken] = await Promise.all([
             Timing.time(c, 'balance_rpc', async () => {
               const result = await Actions.token.getBalance(c.get('getClient')(chainId), {
                 account: address,
@@ -367,18 +382,10 @@ export function addresses(options: addresses.Options = {}) {
               })
               return result.amount
             }),
-            Timing.time(c, 'token', () =>
-              Tokens.resolveToken(c, { address: token, chainId, include: [], snapshot }),
-            ),
+            FeeAmm.feeTokenSet(c, chainId).catch(() => undefined),
+            snapshotPromise,
+            resolvedTokenPromise,
           ])
-          const denomination = query['valuation.currency'] ?? 'USD'
-          const rates = await Valuation.ratesFor(c, {
-            currencies: snapshot.byAddress.has(token) ? [resolvedToken.currency] : [],
-            denomination,
-            oracle,
-          })
-          const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch(() => undefined)
-
           return c.json(
             Response.validated(schema.getAddressBalance.Response, {
               amount: balance.toString(),
@@ -388,12 +395,16 @@ export function addresses(options: addresses.Options = {}) {
               formatted: core_Value.format(balance, resolvedToken.decimals),
               id: token,
               token: resolvedToken,
-              valuation: Valuation.valuationFor({
-                amount: balance,
-                denomination,
-                rates,
-                token: snapshot.byAddress.get(token),
-              }),
+              ...(denomination
+                ? {
+                    valuation: Valuation.valuationFor({
+                      amount: balance,
+                      denomination,
+                      rates,
+                      token: snapshot.byAddress.get(token),
+                    }),
+                  }
+                : {}),
             }),
             200,
           )
@@ -430,7 +441,6 @@ async function getAddressBalances(
     currency,
     denomination,
     feeEligible,
-    feeTokens,
     includeTotalCount,
     limit,
     oracle,
@@ -440,8 +450,9 @@ async function getAddressBalances(
   const cursor = options.cursor ? Cursor.decode(options.cursor, ['uint', 'address']) : undefined
   const offset = options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : 0
 
-  // Validate the requested denomination independently of the current page.
-  await Valuation.ratesFor(c, { currencies: [], denomination, oracle })
+  // Validate an explicit denomination before balance discovery and correction
+  // so dependency failures cannot mask a caller error.
+  if (denomination) await Valuation.ratesFor(c, { currencies: [], denomination, oracle })
 
   // Build the optional `token IN (…)` restriction before hitting TIDX. The
   // verified/`currency` filter and the `feeEligible` filter each contribute a set
@@ -450,17 +461,32 @@ async function getAddressBalances(
   // intersection. If any active filter rules every token out, return an empty
   // page without a round trip. The snapshot is reused for the page enrichment
   // below.
-  const snapshot = await VerifiedTokens.snapshot(c, chainId)
-  const allowed = allowedTokens({ currency, feeEligible, feeTokens, snapshot, verified })
+  const snapshotPromise = VerifiedTokens.snapshot(c, chainId)
+  // Fee filtering can fail before the concurrently started snapshot is awaited.
+  // Observing this branch prevents an unhandled rejection; the later await still propagates it.
+  void snapshotPromise.catch(() => undefined)
+  const [snapshot_filter, feeTokens_filter] = await Promise.all([
+    verified ? snapshotPromise : Promise.resolve(undefined),
+    feeEligible ? FeeAmm.feeTokenSet(c, chainId) : Promise.resolve(undefined),
+  ])
+  const allowed = allowedTokens({
+    currency,
+    feeEligible,
+    feeTokens: feeTokens_filter,
+    snapshot: snapshot_filter,
+    verified,
+  })
   const tokenFilter = allowed?.map((address) => `'${address}'`)
-  if (tokenFilter?.length === 0)
+  if (tokenFilter?.length === 0) {
+    await snapshotPromise
     return {
       data: [],
       ...(includeTotalCount ? { meta: { totalCount: 0, totalCountCapped: false } } : {}),
       nextCursor: null,
     }
+  }
 
-  const holdings = await Timing.time(c, 'balances_discovery', async () => {
+  const holdingsPromise = Timing.time(c, 'balances_discovery', async () => {
     const tokenIn = tokenFilter ? ` AND token IN (${tokenFilter.join(', ')})` : ''
 
     const result = await tidx.fetch({
@@ -481,36 +507,54 @@ async function getAddressBalances(
     })
   })
 
-  if (holdings.length === 0)
+  // Correction starts as soon as discovery completes. Snapshot and fee-token
+  // cache misses continue concurrently until enrichment needs their results.
+  const correctedPromise = holdingsPromise.then(async (holdings) => {
+    if (holdings.length === 0) return []
+    const client = c.get('getClient')(chainId)
+    return Timing.time(c, 'balances_rpc', async () => {
+      // Concurrent reads enter viem's shared batch window and become one
+      // deployless multicall. A failed read fails the request rather than serving
+      // a stale or partial balance page.
+      const results = await Promise.all(
+        holdings.map(async (holding) => {
+          const { amount } = await Actions.token.getBalance(client, {
+            account: address,
+            token: holding.address,
+          })
+          return amount === 0n ? undefined : { address: holding.address, amount: amount.toString() }
+        }),
+      )
+      const rows = results.filter((holding) => holding !== undefined)
+
+      rows.sort((a, b) => {
+        const delta = BigInt(b.amount) - BigInt(a.amount)
+        if (delta !== 0n) return delta > 0n ? 1 : -1
+        return a.address < b.address ? -1 : a.address > b.address ? 1 : 0
+      })
+      return rows
+    })
+  })
+  const feeTokensPromise = feeEligible
+    ? Promise.resolve(feeTokens_filter)
+    : holdingsPromise.then((holdings) =>
+        holdings.length === 0 ? undefined : FeeAmm.feeTokenSet(c, chainId).catch(() => undefined),
+      )
+
+  const [holdings, snapshot, feeTokens, corrected] = await Promise.all([
+    holdingsPromise,
+    snapshotPromise,
+    feeTokensPromise,
+    correctedPromise,
+  ])
+
+  if (holdings.length === 0) {
     return {
       data: [],
       ...(includeTotalCount ? { meta: { totalCount: 0, totalCountCapped: false } } : {}),
       nextCursor: null,
     }
-
-  const client = c.get('getClient')(chainId)
-  const corrected = await Timing.time(c, 'balances_rpc', async () => {
-    // Concurrent reads enter viem's shared batch window and become one
-    // deployless multicall. A failed read fails the request rather than serving
-    // a stale or partial balance page.
-    const results = await Promise.all(
-      holdings.map(async (holding) => {
-        const { amount } = await Actions.token.getBalance(client, {
-          account: address,
-          token: holding.address,
-        })
-        return amount === 0n ? undefined : { address: holding.address, amount: amount.toString() }
-      }),
-    )
-    const rows = results.filter((holding) => holding !== undefined)
-
-    rows.sort((a, b) => {
-      const delta = BigInt(b.amount) - BigInt(a.amount)
-      if (delta !== 0n) return delta > 0n ? 1 : -1
-      return a.address < b.address ? -1 : a.address > b.address ? 1 : 0
-    })
-    return rows
-  })
+  }
 
   const positioned = (() => {
     if (!cursor) return corrected.slice(offset)
@@ -528,7 +572,7 @@ async function getAddressBalances(
     key: (holding) => [holding.amount, holding.address],
   })
 
-  if (page.rows.length === 0)
+  if (page.rows.length === 0) {
     return {
       data: [],
       ...(includeTotalCount
@@ -536,22 +580,38 @@ async function getAddressBalances(
         : {}),
       nextCursor: page.nextCursor,
     }
+  }
 
-  const rates = await Valuation.ratesFor(c, {
-    currencies: page.rows.flatMap((row) => {
-      const held = snapshot.byAddress.get(row.address.toLowerCase())?.currency
-      return held === undefined ? [] : [held]
-    }),
-    denomination,
-    oracle,
-  })
+  const ratesPromise = denomination
+    ? Valuation.ratesFor(c, {
+        currencies: page.rows.flatMap((row) => {
+          const held = snapshot.byAddress.get(row.address.toLowerCase())?.currency
+          return held === undefined ? [] : [held]
+        }),
+        denomination,
+        oracle,
+      })
+    : Promise.resolve(undefined)
 
   // Balance tokens retain their logo and verification metadata by default.
-  const resolved = await Timing.time(c, 'tokens', () =>
+  const resolvedPromise = Timing.time(c, 'tokens', () =>
     Promise.all(
       page.rows.map(async (holding) => {
         try {
           const token = Schema.Address.parse(holding.address.toLowerCase())
+          const verifiedToken = snapshot.byAddress.get(token)
+          // The curated list owns verified-token metadata, but uploaded logos live only in the asset store.
+          if (verifiedToken)
+            return {
+              amount: holding.amount,
+              logoUri:
+                verifiedToken.logoUri ??
+                (await Timing.time(c, 'token_logo', () =>
+                  Tokens.getTokenLogo(c, { address: token, chainId }),
+                ).catch(() => undefined)),
+              metadata: verifiedToken,
+              token,
+            }
           const [logoUri, metadata] = await Promise.all([
             Timing.time(c, 'token_logo', () =>
               Tokens.getTokenLogo(c, { address: token, chainId }),
@@ -567,6 +627,7 @@ async function getAddressBalances(
       }),
     ),
   )
+  const [rates, resolved] = await Promise.all([ratesPromise, resolvedPromise])
 
   const data: z.output<typeof schema.getAddressBalances.Balance>[] = []
   for (const entry of resolved) {
@@ -591,12 +652,16 @@ async function getAddressBalances(
         symbol: entry.metadata.symbol,
         verified: snapshot.byAddress.has(entry.token),
       },
-      valuation: Valuation.valuationFor({
-        amount: BigInt(entry.amount),
-        denomination,
-        rates,
-        token: snapshot.byAddress.get(entry.token),
-      }),
+      ...(denomination
+        ? {
+            valuation: Valuation.valuationFor({
+              amount: BigInt(entry.amount),
+              denomination,
+              rates,
+              token: snapshot.byAddress.get(entry.token),
+            }),
+          }
+        : {}),
     })
   }
 
@@ -620,15 +685,9 @@ declare namespace getAddressBalances {
     /** Opaque keyset cursor anchoring the page; omit for the head page. */
     cursor?: string | undefined
     /** Currency the per-row valuations are denominated in (uppercase). */
-    denomination: string
-    /** When true, restrict the page to fee-usable tokens (members of `feeTokens`). */
+    denomination?: string | undefined
+    /** When true, restrict the page to fee-usable tokens. */
     feeEligible?: boolean | undefined
-    /**
-     * The chain's fee-token set, if resolved (best-effort): flags each row's
-     * `feeEligible` and backs the `feeEligible` filter. Undefined when the lookup
-     * failed, in which case `feeEligible` is omitted from rows.
-     */
-    feeTokens?: ReadonlySet<string> | undefined
     /** When true, include the corrected candidate count in response metadata. */
     includeTotalCount: boolean
     limit: number

package/src/apps/data/routes/blocks.test.ts

@@ -232,20 +232,26 @@ describe('GET /blocks', () => {
 
 describe('GET /blocks/:block (ISO 8601 timestamp)', () => {
   test('resolves an ISO 8601 timestamp to the first block at or after it', async () => {
-    expect(recent).toBeDefined()
-    const recentBlock = await Viem.getClient().getBlock({ blockNumber: recent!.number })
-    const seconds = Number(recentBlock.timestamp)
-    const iso = new Date(seconds * 1000).toISOString()
     const client = TestApp.client()
+    // Seed from TIDX rather than the RPC head, which can advance beyond the
+    // indexer's timestamp lookup watermark.
+    const blocksResponse = await client.v1.blocks.$get({ query: { limit: '5' } }, TestApp.auth)
+    const blocks = await TestApp.json(blocksResponse, Blocks.schema.getBlocks.Response)
+    const indexed = blocks.data[0]
+    expect(blocksResponse.status).toBe(200)
+    expect(indexed).toBeDefined()
+
     const response = await client.v1.blocks[':block'].$get(
-      { param: { block: iso }, query: {} },
+      { param: { block: indexed!.timestamp }, query: {} },
       TestApp.auth,
     )
     const body = await TestApp.json(response, Blocks.schema.getBlock.Response)
     expect(response.status).toBe(200)
     expect(typeof body.number).toBe('number')
     // The returned block's timestamp must be >= the requested timestamp.
-    expect(new Date(body.timestamp).getTime() / 1000).toBeGreaterThanOrEqual(seconds)
+    expect(new Date(body.timestamp).getTime()).toBeGreaterThanOrEqual(
+      new Date(indexed!.timestamp).getTime(),
+    )
   })
 
   test('returns 404 for a far-future timestamp with no indexed block', async () => {

package/src/apps/data/routes/earn.test.ts

@@ -88,6 +88,33 @@ describe('schema.getEarnVaults.Query', () => {
   })
 })
 
+describe('schema.getEarnAddressPositions.Query', () => {
+  test('parses collection filters', () => {
+    const query = Earn.schema.getEarnAddressPositions.Query.parse({
+      limit: '5',
+      'valuation.currency': 'usd',
+      verified: 'true',
+    })
+
+    expect(query.limit).toBe(5)
+    expect(query['valuation.currency']).toBe('USD')
+    expect(query.verified).toBe(true)
+  })
+
+  test('defaults the page size', () => {
+    expect(Earn.schema.getEarnAddressPositions.Query.parse({}).limit).toBe(10)
+  })
+
+  test('rejects vault-collection filters', () => {
+    expect(() =>
+      Earn.schema.getEarnAddressPositions.Query.parse({ capability: 'deposit' }),
+    ).toThrow()
+    expect(() =>
+      Earn.schema.getEarnAddressPositions.Query.parse({ asset: `0x${'aa'.repeat(20)}` }),
+    ).toThrow()
+  })
+})
+
 describe('schema.getEarnVaultEarnings.Response', () => {
   test('enforces status-specific earnings fields', () => {
     const response = {
@@ -540,6 +567,144 @@ describe('GET /v1/earn/vaults/verified', () => {
   )
 })
 
+describe('GET /v1/earn/addresses/:address/positions', () => {
+  test('returns chain selection errors', async () => {
+    const app = TestApp.create({ auth: false, cache })
+    const invalid = await app.request(
+      `/v1/earn/addresses/${TestEarn.positionAddress}/positions?chainId=abc`,
+    )
+    const unsupported = await app.request(
+      `/v1/earn/addresses/${TestEarn.positionAddress}/positions?chainId=999999`,
+    )
+
+    expect([
+      (await TestApp.json(invalid, Schema.ErrorResponse)).error.code,
+      (await TestApp.json(unsupported, Schema.ErrorResponse)).error.code,
+    ]).toStrictEqual(['chain_id_invalid', 'chain_id_unsupported'])
+  })
+
+  test('rejects a malformed account address', async () => {
+    const response = await TestApp.create({ auth: false, cache }).request(
+      '/v1/earn/addresses/not-an-address/positions',
+    )
+
+    expect(response.status).toBe(400)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: { code: 'positions_invalid' },
+    })
+  })
+
+  test('returns an empty verified page without curated vaults', async () => {
+    const app = TestApp.create({ auth: false, cache })
+    const response = await app.request(
+      `/v1/earn/addresses/${TestEarn.positionAddress}/positions?verified=true`,
+    )
+
+    expect(response.status).toBe(200)
+    expect(
+      await TestApp.json(response, Earn.schema.getEarnAddressPositions.Response),
+    ).toStrictEqual({ data: [], nextCursor: null })
+  })
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'lists non-zero verified positions for an account',
+    async () => {
+      const db = TestApp.database()
+      // Valuation resolves through the curated verified list, so seed it.
+      await TestApp.verifiedSeed(db, TestEarn.chain.id)
+      await core_EarnVaults.upsert(db, TestEarn.verifiedVault)
+      await core_EarnVaults.upsert(db, {
+        ...TestEarn.verifiedVault,
+        description: 'Active-earnings Earn deployment.',
+        label: 'Active btPATHUSD Earn',
+        vaultAddress: TestEarn.activeEarningsVaultAddress,
+      })
+      const app = TestApp.create({ auth: false, cache, db, zones: [TestEarn.zone] })
+      const response = await app.request(
+        `/v1/earn/addresses/${TestEarn.activeEarningsAddress}/positions?chainId=${TestEarn.chain.id}&verified=true&valuation.currency=USD`,
+      )
+
+      expect(response.status).toBe(200)
+      const body = await TestApp.json(response, Earn.schema.getEarnAddressPositions.Response)
+      expect(body.data.every((position) => BigInt(position.shareAmount.amount) > 0n)).toBe(true)
+      const row = body.data.find(
+        (position) => position.vaultAddress === TestEarn.activeEarningsVaultAddress,
+      )
+      expect(row).toBeDefined()
+      if (!row) return
+      // Amounts render in their own token's display currency and precision.
+      expect(row.shareAmount.currency).toBe(row.shareToken.currency)
+      expect(row.shareAmount.decimals).toBe(row.shareToken.decimals)
+      expect(row.assetAmount.currency).toBe(row.assetToken.currency)
+      expect(row.assetAmount.decimals).toBe(row.assetToken.decimals)
+      // A USD-denominated asset values identically without consulting rates.
+      expect(row.valuation).toStrictEqual({ amount: row.assetAmount.formatted, currency: 'USD' })
+      expect(body.meta).toBeUndefined()
+      expect({
+        assetToken: row.assetToken.address,
+        formattedShape: /^\d+(\.\d+)?$/.test(row.assetAmount.formatted),
+        id: row.id,
+        sharesHeld: BigInt(row.shareAmount.amount) > 0n,
+        valued: BigInt(row.assetAmount.amount) > 0n,
+        vaultAddress: row.vaultAddress,
+        verified: row.verified,
+      }).toMatchInlineSnapshot(`
+        {
+          "assetToken": "0x20c0000000000000000000000000000000000001",
+          "formattedShape": true,
+          "id": "0x3e4405801a1bee1b58394228ea0b44b667e222fc",
+          "sharesHeld": true,
+          "valued": true,
+          "vaultAddress": "0x3e4405801a1bee1b58394228ea0b44b667e222fc",
+          "verified": true,
+        }
+      `)
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'discovers held vaults from indexed share balances',
+    async () => {
+      const app = TestApp.create({ auth: false, cache, zones: [TestEarn.zone] })
+      const response = await app.request(
+        `/v1/earn/addresses/${TestEarn.activeEarningsAddress}/positions?chainId=${TestEarn.chain.id}`,
+      )
+
+      expect(response.status).toBe(200)
+      const body = await TestApp.json(response, Earn.schema.getEarnAddressPositions.Response)
+      expect(body.data.map((position) => position.vaultAddress)).toContain(
+        TestEarn.activeEarningsVaultAddress,
+      )
+      expect(
+        body.data.every(
+          (position) =>
+            position.id === position.vaultAddress &&
+            !position.verified &&
+            /^\d+$/.test(position.assetAmount.amount) &&
+            BigInt(position.shareAmount.amount) > 0n &&
+            position.assetToken.address.startsWith('0x20c0') &&
+            position.shareToken.address.startsWith('0x20c0'),
+        ),
+      ).toBe(true)
+
+      // An address-keyset cursor excludes every vault at or before it.
+      const cursor = Cursor.encode([TestEarn.activeEarningsVaultAddress])
+      const paged = await app.request(
+        `/v1/earn/addresses/${TestEarn.activeEarningsAddress}/positions?chainId=${TestEarn.chain.id}&cursor=${encodeURIComponent(cursor)}`,
+      )
+      expect(paged.status).toBe(200)
+      const pagedBody = await TestApp.json(paged, Earn.schema.getEarnAddressPositions.Response)
+      expect(
+        pagedBody.data.every(
+          (position) => position.vaultAddress > TestEarn.activeEarningsVaultAddress,
+        ),
+      ).toBe(true)
+    },
+    90_000,
+  )
+})
+
 describe('GET /v1/earn/vaults/:vaultId', () => {
   test('rejects a malformed vault address', async () => {
     const app = TestApp.create({ auth: false, cache })
@@ -1375,6 +1540,7 @@ describe('OpenAPI', () => {
 
     expect(Object.keys(spec.paths)).toEqual(
       expect.arrayContaining([
+        '/v1/earn/addresses/{address}/positions',
         '/v1/earn/vaults',
         '/v1/earn/vaults/verified',
         '/v1/earn/vaults/{vaultId}',
@@ -1446,6 +1612,37 @@ describe('OpenAPI', () => {
     expect(vaultId?.schema?.examples).toStrictEqual([TestEarn.mainnetVaultAddress])
   })
 
+  test('documents address-position inputs and responses', async () => {
+    const app = TestApp.create({ auth: false, cache })
+    const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+    const operation = spec.paths['/v1/earn/addresses/{address}/positions']?.get
+    const address = operation?.parameters?.find((parameter) => parameter.name === 'address')
+    const denomination = operation?.parameters?.find(
+      (parameter) => parameter.name === 'valuation.currency',
+    )
+    const verified = operation?.parameters?.find((parameter) => parameter.name === 'verified')
+    const response = JSON.stringify(operation?.responses)
+
+    expect(operation?.description).toContain('currently holds shares')
+    expect(address?.schema?.examples).toStrictEqual([TestEarn.positionAddress])
+    expect(denomination?.description).toContain('nominal value')
+    expect(verified?.description).toContain('registry-curated')
+    expect(verified?.schema?.examples).toStrictEqual([true])
+    expect(response).toContain('"chain_id_invalid"')
+    expect(response).toContain('"chain_id_unsupported"')
+    expect(response).toContain('"positions_invalid"')
+    expect(response).toContain('"query_invalid"')
+    expect(response).toContain('Stable resource ID for this position')
+    expect(response).toContain('Current asset value of the held shares')
+    expect(response).toContain('"assetAmount"')
+    expect(response).toContain('"shareAmount"')
+    expect(response).toContain('"valuation"')
+    expect(response).toContain('"vaultAddress"')
+    expect(response).toContain('"nextCursor"')
+    // Token references embed the trimmed token object, not a bare address.
+    expect(response).toContain('"symbol"')
+  })
+
   test('documents vault-earnings variants', async () => {
     const app = TestApp.create({ auth: false, cache })
     const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument