@compass-labs/api-sdk 2.1.34 → 2.1.35-rc.0

package/src/models/components/batchedsafeoperationsresponseinput.ts

@@ -24,7 +24,7 @@ import {
  */
 export type BatchedSafeOperationsResponseInput = {
   /**
-   * The EIP-712 domain separator for Safe transactions.
+   * The EIP-712 domain separator.
    */
   domain:
     CompassApiBackendV2ModelsSafeTransactResponseBatchedSafeOperationsEip712Domain;
@@ -38,7 +38,7 @@ export type BatchedSafeOperationsResponseInput = {
    */
   primaryType: "SafeTx";
   /**
-   * The message data for a Safe transaction.
+   * The message data for the transaction.
    */
   message: SafeTxMessage;
 };

package/src/models/components/batchedsafeoperationsresponseoutput.ts

@@ -21,7 +21,7 @@ import { SafeTxMessage, SafeTxMessage$inboundSchema } from "./safetxmessage.js";
  */
 export type BatchedSafeOperationsResponseOutput = {
   /**
-   * The EIP-712 domain separator for Safe transactions.
+   * The EIP-712 domain separator.
    */
   domain:
     CompassApiBackendV2ModelsSafeTransactResponseBatchedSafeOperationsEip712Domain;
@@ -35,7 +35,7 @@ export type BatchedSafeOperationsResponseOutput = {
    */
   primaryType: "SafeTx";
   /**
-   * The message data for a Safe transaction.
+   * The message data for the transaction.
    */
   message: SafeTxMessage;
 };

package/src/models/components/compassapibackendv2modelssafetransactresponsebatchedsafeoperationseip712domain.ts

@@ -8,16 +8,16 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * The EIP-712 domain separator for Safe transactions.
+ * The EIP-712 domain separator.
  */
 export type CompassApiBackendV2ModelsSafeTransactResponseBatchedSafeOperationsEip712Domain =
   {
     /**
-     * Chain ID for the Safe transaction
+     * Chain ID
      */
     chainId: number;
     /**
-     * Address of the Safe contract
+     * Address of the Product Account
      */
     verifyingContract: string;
   };

package/src/models/components/safetxmessage.ts

@@ -13,7 +13,7 @@ import {
 } from "./operationtype.js";
 
 /**
- * The message data for a Safe transaction.
+ * The message data for the transaction.
  */
 export type SafeTxMessage = {
   /**
@@ -33,7 +33,7 @@ export type SafeTxMessage = {
    */
   operation: OperationType;
   /**
-   * Gas for the Safe transaction
+   * Gas for the transaction
    */
   safeTxGas: string;
   /**
@@ -53,7 +53,7 @@ export type SafeTxMessage = {
    */
   refundReceiver: string;
   /**
-   * Safe transaction nonce
+   * Transaction nonce
    */
   nonce: string;
 };

package/src/models/components/sponsorgasrequest.ts

@@ -31,7 +31,7 @@ export type SponsorGasRequestEip712 =
 
 export type SponsorGasRequest = {
   /**
-   * The owner of the smart account's address.
+   * The wallet address that owns the Earn Account.
    */
   owner: string;
   /**

package/src/sdk/earn.ts

@@ -20,7 +20,14 @@ export class Earn extends ClientSDK {
    * List earn positions
    *
    * @remarks
-   * This endpoint fetches all Compass Earn positions with PnL information.
+   * List all Earn positions for a given owner with PnL tracking.
+   *
+   * Returns position data including current balance, cost basis, and profit and loss.
+   * Use this endpoint to display portfolio performance, track yields over time, or build
+   * position management interfaces.
+   *
+   * Positions are tracked across all venue types (vaults and Aave markets). Each
+   * position includes the venue address, deposited amount, and performance metrics.
    */
   async earnPositions(
     request: operations.V2EarnPositionsRequest,
@@ -37,9 +44,13 @@ export class Earn extends ClientSDK {
    * List vaults
    *
    * @remarks
-   * List information about 4626 vaults.
+   * List ERC-4626 yield vaults across DeFi venues.
+   *
+   * Returns vault data including APY, TVL, and underlying asset information. Use this endpoint to discover yield opportunities, compare rates across venues, or build vault selection interfaces.
+   *
+   * Supports dozens of vaults and markets like Morpho and other ERC-4626 compatible yield venues.
    *
-   * These are earn opportunities for protocols like morpho.
+   * To deposit into a vault, use the [manage endpoint](https://docs.compasslabs.ai/v2/api-reference/earn/manage-earn-position) with `venue_type=VAULTS`.
    */
   async earnVaults(
     request: operations.V2EarnVaultsRequest,
@@ -56,16 +67,13 @@ export class Earn extends ClientSDK {
    * List aave markets
    *
    * @remarks
-   * List all aave markets with their supply and borrow rates.
+   * List Aave lending markets with supply and borrow rates.
    *
-   * Returns rates organized by token symbol, with chain-specific data for each token.
-   * Each token includes rates for all chains where it's available, plus information
-   * about which chain offers the highest supply APY.
+   * Returns rates organized by token symbol, with chain-specific data for each token. Each token includes rates for all chains where it's available, plus information about which chain offers the highest supply APY.
    *
-   * APY values are returned in percentage format (e.g., 4.5 means 4.5%). Tokens with
-   * zero APY on both supply and borrow are excluded.
+   * APY values are returned in percentage format (e.g., 4.5 means 4.5%). Tokens with zero APY on both supply and borrow are excluded.
    *
-   * Optionally filter by chain.
+   * To deposit into an Aave market, use the [manage endpoint](https://docs.compasslabs.ai/v2/api-reference/earn/manage-earn-position) with `venue_type=AAVE`.
    */
   async earnAaveMarkets(
     request: operations.V2EarnAaveMarketsRequest,
@@ -82,17 +90,15 @@ export class Earn extends ClientSDK {
    * Create earn account
    *
    * @remarks
-   * Create an Earn Account.
+   * Create an Earn Account for a wallet address.
    *
-   * Before creating Earn positions, the `owner` must create an Earn Account associated with their wallet address.
+   * Before depositing into venues or managing positions, the owner must create an Earn Account. Each wallet address has one Earn Account per chain.
    *
-   * Only the `owner` has the authority to sign transactions for this account. This can be done in one of two ways:
+   * Returns an unsigned transaction to create the account. The `sender` signs and broadcasts this transaction.
    *
-   * 1) **No gas-sponsorship:** The `owner` signs a transaction and submits it to the network for execution. The `owner` covers the cost of gas in this case.
+   * **If owner pays gas:** Set `sender` to the owner's address.
    *
-   * 2) **Gas-sponsorship:** The `owner` does an off-chain EIP-712 signature and submits this signature to the 'Prepare gas-sponsored transaction' endpoint (`/gas_sponsorship/prepare`). Here, another wallet address is set as `sender`. This wallet will sign, submit and cover the gas fees of the transaction.
-   *
-   * The creation of an Earn Account itself can be a gas-sponsored transaction by setting the `sender` to the wallet which will sign and send the transaction.
+   * **If someone else pays gas:** Set `sender` to the wallet that will sign and broadcast the transaction on behalf of the owner.
    */
   async earnCreateAccount(
     request: components.CreateAccountRequest,
@@ -109,14 +115,23 @@ export class Earn extends ClientSDK {
    * Transfer tokens to/from account
    *
    * @remarks
-   * Transfer tokens to and from an Earn Account.
+   * Transfer tokens between an owner's wallet and their Earn Account.
+   *
+   * Use `DEPOSIT` to move tokens from the owner's wallet into their Earn Account. Use `WITHDRAW` to move tokens from the Earn Account back to the owner's wallet.
+   *
+   * **Gas-sponsored deposits** require two steps:
    *
-   * If `DEPOSIT`'` is selected, tokens will be transferred from the `owner`'s wallet into their Earn Account.
+   * **Step 1 (once per token):** Set up Permit2 allowance
+   * 1. Call [/gas_sponsorship/approve_transfer](https://docs.compasslabs.ai/v2/api-reference/gas-sponsorship/approve-token-transfer) to get EIP-712 typed data
+   * 2. Owner signs the typed data
+   * 3. Submit signature + typed data to [/gas_sponsorship/prepare](https://docs.compasslabs.ai/v2/api-reference/gas-sponsorship/prepare-gas-sponsored-transaction)
    *
-   * If `WITHDRAW` is selected, tokens will be transferred from the `owner`'s Earn Account into their wallet.
+   * **Step 2 (each transfer):** Execute the gas-sponsored transfer
+   * 1. Call this endpoint with `gas_sponsorship=true` to get EIP-712 typed data
+   * 2. Owner signs the typed data
+   * 3. Submit signature + typed data to [/gas_sponsorship/prepare](https://docs.compasslabs.ai/v2/api-reference/gas-sponsorship/prepare-gas-sponsored-transaction)
    *
-   * If a gas-sponsored `DEPOSIT` transfer is desired for a given token, a one-time Permit2 allowance must be set before proceeding. This is common practice for many other applications and, for many `owner`s, this one-time allowance will already have been set for the token they would like to transfer.
-   * Once the one-time allowance is set for a given token and `gas_sponsorship` is set to 'true', EIP-712 typed data will be returned and can be signed off-chain by the user. This signature can then be submitted to the 'Prepare gas-sponsored transaction' endpoint (`/gas_sponsorship/prepare`) where a `sender` can be set for the transaction.
+   * **Note:** This endpoint moves tokens to/from the Earn Account itself—not into yield venues. To deposit into a vault or Aave market, use the [manage endpoint](https://docs.compasslabs.ai/v2/api-reference/earn/manage-earn-position).
    */
   async earnTransfer(
     request: components.EarnTransferRequest,
@@ -133,24 +148,20 @@ export class Earn extends ClientSDK {
    * Manage earn position
    *
    * @remarks
-   * Manage an Earn position for a given `owner`'s Earn Account.
+   * Deposit into or withdraw from a yield venue.
    *
-   * The `owner` is the main wallet address that owns and controls the Earn Account. It is not the Earn Account address itself.
+   * Use `DEPOSIT` to move tokens from the Earn Account into a vault or Aave market. Use `WITHDRAW` to move tokens back from a venue into the Earn Account.
    *
-   * Venue Types:
-   * - VAULTS
-   * - AAVE
+   * **Venue types:**
+   * - `VAULTS`: ERC-4626 vaults (see [/vaults](https://docs.compasslabs.ai/v2/api-reference/earn/list-vaults) for available options)
+   * - `AAVE`: Aave lending pools (see [/aave_markets](https://docs.compasslabs.ai/v2/api-reference/earn/list-aave-markets) for available options)
    *
-   * If `DEPOSIT` is selected for `action`, tokens will be deposited into the selected venue address from the Earn Account associated with the  `owner` wallet.
+   * **Fees:** A fee can be configured and deducted from the transaction amount:
+   * - `FIXED`: A fixed token amount (e.g., 0.1 means 0.1 tokens)
+   * - `PERCENTAGE`: A percentage of the amount (e.g., 1.5 means 1.5%)
+   * - `PERFORMANCE`: A percentage of realized profit (withdrawals only)
    *
-   * If `WITHDRAW` is selected for `action`, tokens will be withdrawn from the selected venue address back into the Earn Account associated with the `owner` wallet.
-   *
-   * A fee can be configured. This fee is deducted from the total `amount`. It can be expressed as:
-   * - `FIXED`: a fixed token amount (e.g., 0.1 means 0.1 tokens)
-   * - `PERCENTAGE`: a percentage of the transaction amount (e.g., 1.5 means 1.5%)
-   * - `PERFORMANCE`: a percentage of realized profit using FIFO cost basis (e.g., 10 means 10% of profit). Only applicable for withdrawals.
-   *
-   * The transaction can be gas-sponsored by an arbitrary wallet address which will sign, submit and pay the required gas for the transaction. If `gas_sponsorship` is set to `true`, EIP-712 typed data will be returned that must be signed by the `owner` and submitted to the 'Prepare gas-sponsored transaction' endpoint (`/gas_sponsorship/prepare`) where the `sender` of the transaction can be set.
+   * **Gas sponsorship:** Set `gas_sponsorship=true` to receive EIP-712 typed data. Owner signs the typed data, then submit to [/gas_sponsorship/prepare](https://docs.compasslabs.ai/v2/api-reference/gas-sponsorship/prepare-gas-sponsored-transaction).
    */
   async earnManage(
     request: components.EarnManageRequest,
@@ -168,6 +179,12 @@ export class Earn extends ClientSDK {
    *
    * @remarks
    * Swap tokens within an Earn Account.
+   *
+   * Use this endpoint to exchange one token for another without transferring funds out of the Earn Account.
+   *
+   * The swap executes atomically within the Earn Account and can be combined with other actions using the [bundle endpoint](https://docs.compasslabs.ai/v2/api-reference/earn/execute-multiple-earn-actions). For example, swap ETH to USDC, then deposit USDC into a vault—all in one transaction.
+   *
+   * Returns either an unsigned transaction (when `gas_sponsorship=false`) or EIP-712 typed data for off-chain signing (when `gas_sponsorship=true`). For gas-sponsored swaps, submit the signed typed data to `/gas_sponsorship/prepare`.
    */
   async earnSwap(
     request: components.EarnSwapRequest,
@@ -184,20 +201,19 @@ export class Earn extends ClientSDK {
    * Execute multiple earn actions
    *
    * @remarks
-   * This endpoint allows combining multiple actions (swaps, vault
-   * deposits/withdrawals, Aave deposits/withdrawals) into a single atomic transaction
-   * executed via the Earn account).
+   * Combine multiple actions into a single atomic transaction.
+   *
+   * Bundle swaps and venue deposits/withdrawals into one transaction executed through the Earn Account. This saves gas compared to executing actions separately and ensures all actions succeed or fail together.
    *
-   * **Example Use Case:** Swap USDC to AUSD, then deposit AUSD into a vault - all in one transaction.
+   * **Example:** Swap AUSD to USDC, then deposit USDC into a vault - all in one transaction.
    *
-   * Actions are executed in the order they are provided. Each action type has its own parameters:
+   * **Action types:**
+   * - `V2_SWAP`: Swap tokens within the Earn Account
+   * - `V2_MANAGE`: Deposit/withdraw to ERC-4626 vaults or Aave markets
    *
-   * - **V2_SWAP**: Swapping tokens within the Earn Account
-   * - **V2_MANAGE**: Manage positions - deposit/withdraw to ERC-4626 vaults or Aave lending pool
+   * Actions execute in the order provided.
    *
-   * The bundled transaction can be gas-sponsored by setting `gas_sponsorship=true`.
-   * This returns EIP-712 typed data that the owner must sign and submit to
-   * `/gas_sponsorship/prepare` for execution by a gas sponsor.
+   * **Gas sponsorship:** Set `gas_sponsorship=true` to receive EIP-712 typed data. Owner signs the typed data, then submit to [/gas_sponsorship/prepare](https://docs.compasslabs.ai/v2/api-reference/gas-sponsorship/prepare-gas-sponsored-transaction).
    */
   async earnBundle(
     request: components.V2BundleRequest,

package/src/sdk/gassponsorship.ts

@@ -13,11 +13,17 @@ export class GasSponsorship extends ClientSDK {
    * Prepare gas-sponsored transaction
    *
    * @remarks
-   * Prepare a gas-sponsored transaction to be signed and submitted by `sender`.
+   * Prepare a gas-sponsored transaction from signed EIP-712 typed data.
    *
-   * The `owner` submits their off-chain signature of EIP-712 typed data along with the data itself.
+   * Submit the `owner`'s off-chain signature along with the EIP-712 typed data that was signed. Returns an unsigned transaction for the `sender` to sign and broadcast.
    *
-   * The `sender` will sign and submit the transaction returned from this endpoint, effectively sponsoring the gas for the transaction on behalf of the `owner`.
+   * **How gas sponsorship works:**
+   * 1. Call an endpoint with `gas_sponsorship=true` (e.g., [/earn/transfer](https://docs.compasslabs.ai/v2/api-reference/earn/transfer-tokens-tofrom-account), [/earn/manage](https://docs.compasslabs.ai/v2/api-reference/earn/manage-earn-position)) to get EIP-712 typed data
+   * 2. Owner signs the typed data off-chain
+   * 3. Submit signature + typed data to this endpoint
+   * 4. Sender signs and broadcasts the returned transaction, paying gas on behalf of the owner
+   *
+   * **Note:** For gas-sponsored deposits via [/earn/transfer](https://docs.compasslabs.ai/v2/api-reference/earn/transfer-tokens-tofrom-account), the owner must first set up a Permit2 allowance using [/approve_transfer](https://docs.compasslabs.ai/v2/api-reference/gas-sponsorship/approve-token-transfer) (once per token).
    */
   async gasSponsorshipPrepare(
     request: components.SponsorGasRequest,
@@ -34,16 +40,16 @@ export class GasSponsorship extends ClientSDK {
    * Approve token transfer
    *
    * @remarks
-   * Prepare a one-time permit2 approval transaction for a given token.
+   * Set up a one-time Permit2 allowance for gas-sponsored token transfers.
+   *
+   * Only required when using [/earn/transfer](https://docs.compasslabs.ai/v2/api-reference/earn/transfer-tokens-tofrom-account) with `gas_sponsorship=true`. This allowance only needs to be set up once per token.
    *
-   * This is only required if the `owner` would like to transfer tokens from their wallet to their Earn Account with gas-sponsorship.
+   * **With gas sponsorship (`gas_sponsorship=true`):**
+   * - Returns EIP-712 typed data for the owner to sign off-chain
+   * - Submit signature + typed data to [/prepare](https://docs.compasslabs.ai/v2/api-reference/gas-sponsorship/prepare-gas-sponsored-transaction)
+   * - Only works for tokens that support EIP-2612 permit (e.g., USDC)
    *
-   * This approval transaction itself can be submitted with gas-sponsorship.
-   * In this case, EIP-712 typed data will be returned and should be signed by the `owner` off-chain.
-   * This signature can then be submitted to the 'Prepare gas-sponsored transaction' endpoint (`/gas_sponsorship/prepare`).
-   * Gas-sponsored approvals can only be achieved by ERC-20 tokens that support permit (EIP-2612).
-   * Some tokens, like USDT and WETH, do not allow for this behavior.
-   * In the case of non-permit tokens, the one-time approval transaction can be submitted in the conventional manner where the `owner` must sign, submit and pay gas for the transaction.
+   * Some tokens, like USDT and WETH, do not support EIP-2612 permit. For these tokens, set `gas_sponsorship=false` to receive an unsigned transaction that the owner must sign, submit, and pay gas for.
    */
   async gasSponsorshipApproveTransfer(
     request: components.ApproveTransferRequest,