diff --git a/src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPosition.tjava b/src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPosition.tjava
index 13c07d3..238643b 100644
--- a/src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPosition.tjava
+++ b/src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPosition.tjava
@@ -2,6 +2,19 @@ package com.r35157.libs.jupiter.perps;
 
 import java.math.BigDecimal;
 
+/**
+ * Represents a Jupiter Perps position.
+ *
+ * <p>A Jupiter Perps position is represented on-chain by a Solana account owned by
+ * the Jupiter Perps program. This record contains the public API view of such a
+ * position.</p>
+ *
+ * <p>The initial version of this API only exposes the position account and the entry
+ * price. More position fields may be added later as the Jupiter Perps API matures.</p>
+ *
+ * @param positionAccount the Solana account address of the Jupiter Perps position
+ * @param entryPrice the entry price of the position, denominated in USDC
+ */
 public record JupiterPerpsPosition(
         ΩJupiterPerpsPositionAccountΩ positionAccount,
         ΩUSDCPriceΩ entryPrice
diff --git a/src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPositionService.tjava b/src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPositionService.tjava
index b35b9be..2f47ad3 100644
--- a/src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPositionService.tjava
+++ b/src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPositionService.tjava
@@ -2,7 +2,29 @@ package com.r35157.libs.jupiter.perps;
 
 import java.io.IOException;
 
+/**
+ * Service for reading Jupiter Perps positions.
+ *
+ * <p>This service is read-only. It does not open, close, modify, or sign transactions
+ * for Jupiter Perps positions.</p>
+ *
+ * <p>The first supported operation is reading a known Jupiter Perps position account
+ * and returning its decoded position data.</p>
+ */
 public interface JupiterPerpsPositionService {
+    /**
+     * Reads a Jupiter Perps position from a known position account.
+     *
+     * <p>The supplied account must be the Solana account that stores the Jupiter Perps
+     * position state. It is not the wallet address, token account, custody account, pool
+     * account, or position request account.</p>
+     *
+     * @param positionAccount the Solana account address of the Jupiter Perps position
+     * @return the decoded Jupiter Perps position
+     * @throws IOException if the position account could not be fetched or decoded
+     * @throws InterruptedException if the calling thread is interrupted while fetching
+     *                              the position account
+     */
     JupiterPerpsPosition getPosition(ΩJupiterPerpsPositionAccountΩ positionAccount)
             throws IOException, InterruptedException;
 }
\ No newline at end of file