> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compasslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Swap tokens within Earn Account

> 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`.



## OpenAPI

````yaml /v2/combined_spec.json post /v2/earn/swap
openapi: 3.1.0
info:
  title: Compass API
  description: Compass Labs DeFi API
  version: 0.0.1
servers:
  - url: https://api.compasslabs.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /v2/earn/swap:
    post:
      tags:
        - Earn
      summary: Swap tokens within Earn Account
      description: >-
        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`.
      operationId: v2_earn_swap
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EarnSwapRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarnSwapResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: python
          label: Python (SDK)
          source: |-
            from compass_api_sdk import CompassAPI, models


            with CompassAPI(
                api_key_auth="<YOUR_API_KEY_HERE>",
            ) as compass_api:

                res = compass_api.earn.earn_swap(token_in="USDC", token_out="USDT", amount_in="0.01", owner="0x06A9aF046187895AcFc7258450B15397CAc67400", chain=models.Chain.BASE, slippage="0.5", gas_sponsorship=False)

                # Handle response
                print(res)
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { CompassApiSDK } from "@compass-labs/api-sdk";

            const compassApiSDK = new CompassApiSDK({
              apiKeyAuth: "<YOUR_API_KEY_HERE>",
            });

            async function run() {
              const result = await compassApiSDK.earn.earnSwap({
                tokenIn: "USDC",
                tokenOut: "USDT",
                amountIn: "0.01",
                slippage: "0.5",
                owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
                chain: "base",
                gasSponsorship: false,
              });

              console.log(result);
            }

            run();
components:
  schemas:
    EarnSwapRequest:
      properties:
        action_type:
          type: string
          const: V2_SWAP
          title: Action Type
          description: Action type identifier for swap operations.
          default: V2_SWAP
        token_in:
          type: string
          title: Token
          description: >-
            Token to sell (input). Provide a token symbol from a limited set
            (e.g., 'USDC') or any token address.
          examples:
            - USDC
            - '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
          default: USDC
        token_out:
          type: string
          title: Token
          description: >-
            Token to buy (output). Provide a token symbol from a limited set
            (e.g., 'USDT') or any token address.
          examples:
            - USDT
            - '0xdAC17F958D2ee523a2206206994597C13D831ec7'
          default: USDT
        amount_in:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount In
          description: Human-readable amount of `token_in` to swap (token units, not wei).
          examples:
            - 1.5
          default: '0.01'
        slippage:
          anyOf:
            - type: number
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Slippage
          description: Maximum slippage tolerance as a percentage (e.g., 0.5 = 0.5%).
          default: '0.5'
          examples:
            - 0.5
        owner:
          type: string
          title: Owner
          description: The owner's wallet address.
          default: '0x06A9aF046187895AcFc7258450B15397CAc67400'
          examples:
            - '0x06A9aF046187895AcFc7258450B15397CAc67400'
        chain:
          $ref: '#/components/schemas/Chain'
          description: Target blockchain network where the swap will execute.
          default: base
          examples:
            - base
        gas_sponsorship:
          type: boolean
          title: Gas Sponsorship
          description: >-
            Optionally request gas sponsorship. If `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`).
          default: false
          examples:
            - false
      type: object
      required:
        - token_in
        - token_out
        - amount_in
        - owner
        - chain
      title: EarnSwapRequest
      description: >-
        Request model for swap endpoint.


        Inherits swap params and adds context fields (owner, chain,
        gas_sponsorship).
      default:
        owner: '0x06A9aF046187895AcFc7258450B15397CAc67400'
        chain: base
        token_in: USDC
        token_out: USDT
        amount_in: '0.01'
        slippage: '0.5'
        gas_sponsorship: false
    EarnSwapResponse:
      properties:
        transaction:
          anyOf:
            - $ref: '#/components/schemas/UnsignedTransaction'
            - type: 'null'
          description: >-
            Unsigned transaction for direct execution. Present when
            gas_sponsorship=false.
        eip_712:
          anyOf:
            - $ref: '#/components/schemas/BatchedSafeOperationsResponse-Output'
            - type: 'null'
          description: >-
            EIP-712 typed data for gas-sponsored execution. Present when
            gas_sponsorship=true.
        estimated_amount_out:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Estimated Amount Out
          description: Estimated amount of output token received from the swap.
      type: object
      required:
        - estimated_amount_out
      title: EarnSwapResponse
      example:
        estimated_amount_out: '2485.123456'
        transaction:
          chainId: '0x2105'
          data: >-
            0x8d80ff0a0000000000000000000000000000000000000000000000000000000000000020
          from: '0x4A83b4413CF41C3244027e1590E35a0F48403F0c'
          gas: '0x7a120'
          maxFeePerGas: '0x59682f00'
          maxPriorityFeePerGas: '0x3b9aca00'
          nonce: '0x5'
          to: '0x6B90E8B4E3E971E74C1A47a3a20976377E2dB4b1'
          value: '0x0'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Chain:
      type: string
      enum:
        - base
        - ethereum
        - arbitrum
        - hyperevm
        - tempo
        - bsc
      title: Chain
      description: The chain to use.
    UnsignedTransaction:
      properties:
        chainId:
          type: string
          title: Chainid
          description: The chain id of the transaction
        data:
          type: string
          title: Data
          description: The data of the transaction
        from:
          type: string
          title: From
          description: The sender of the transaction
        gas:
          anyOf:
            - type: string
            - type: 'null'
          title: Gas
          description: The gas of the transaction
        to:
          type: string
          title: To
          description: The recipient of the transaction
        value:
          type: string
          title: Value
          description: The value of the transaction
        nonce:
          type: string
          title: Nonce
          description: The nonce of the address
        maxFeePerGas:
          type: string
          title: Maxfeepergas
          description: The max fee per gas of the transaction
        maxPriorityFeePerGas:
          type: string
          title: Maxpriorityfeepergas
          description: The max priority fee per gas of the transaction
      type: object
      required:
        - chainId
        - data
        - from
        - gas
        - to
        - value
        - nonce
        - maxFeePerGas
        - maxPriorityFeePerGas
      title: UnsignedTransaction
      example:
        chainId: '0x2105'
        data: >-
          0x1688f0b900000000000000000000000029fcb43b46531bca003ddc8fcb67ffe91900c762000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000675f4a3d
        from: '0x4A83b4413CF41C3244027e1590E35a0F48403F0c'
        gas: '0x7a120'
        maxFeePerGas: '0x59682f00'
        maxPriorityFeePerGas: '0x3b9aca00'
        nonce: '0x5'
        to: '0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67'
        value: '0x0'
    BatchedSafeOperationsResponse-Output:
      properties:
        domain:
          $ref: >-
            #/components/schemas/compass__api_backend__v2__models__safe__transact__response__batched_safe_operations__EIP712Domain
          description: EIP-712 domain separator
        types:
          $ref: >-
            #/components/schemas/compass__api_backend__v2__models__safe__transact__response__batched_safe_operations__EIP712Types
          description: EIP-712 type definitions
        primaryType:
          type: string
          const: SafeTx
          title: Primarytype
          description: Primary type for the structured data
        message:
          $ref: '#/components/schemas/SafeTxMessage'
          description: Safe transaction message data
      type: object
      required:
        - domain
        - types
        - primaryType
        - message
      title: BatchedSafeOperationsResponse
      description: Response containing EIP-712 typed data for Safe transaction signing.
      example:
        domain:
          chainId: 8453
          verifyingContract: '0x6B90E8B4E3E971E74C1A47a3a20976377E2dB4b1'
        message:
          baseGas: '0'
          data: >-
            0x8d80ff0a0000000000000000000000000000000000000000000000000000000000000020
          gasPrice: '0'
          gasToken: '0x0000000000000000000000000000000000000000'
          nonce: '7'
          operation: 1
          refundReceiver: '0x0000000000000000000000000000000000000000'
          safeTxGas: '0'
          to: '0x93C23AAE4793C14D6DF35D2A2A2234204e1559dA'
          value: '0'
        primaryType: SafeTx
        types:
          EIP712Domain:
            - name: chainId
              type: uint256
            - name: verifyingContract
              type: address
          SafeTx:
            - name: to
              type: address
            - name: value
              type: uint256
            - name: data
              type: bytes
            - name: operation
              type: uint8
            - name: safeTxGas
              type: uint256
            - name: baseGas
              type: uint256
            - name: gasPrice
              type: uint256
            - name: gasToken
              type: address
            - name: refundReceiver
              type: address
            - name: nonce
              type: uint256
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    compass__api_backend__v2__models__safe__transact__response__batched_safe_operations__EIP712Domain:
      properties:
        chainId:
          type: integer
          title: Chainid
          description: Chain ID
        verifyingContract:
          type: string
          title: Verifyingcontract
          description: Address of the Product Account
      type: object
      required:
        - chainId
        - verifyingContract
      title: EIP712Domain
      description: The EIP-712 domain separator.
    compass__api_backend__v2__models__safe__transact__response__batched_safe_operations__EIP712Types:
      properties:
        EIP712Domain:
          items:
            $ref: '#/components/schemas/EIP712DomainField'
          type: array
          title: Eip712Domain
          description: EIP712Domain type definition
        SafeTx:
          items:
            $ref: '#/components/schemas/SafeTxField'
          type: array
          title: Safetx
          description: SafeTx type definition
      type: object
      required:
        - EIP712Domain
        - SafeTx
      title: EIP712Types
      description: The type definitions for EIP-712 structured data.
    SafeTxMessage:
      properties:
        to:
          type: string
          title: To
          description: Destination address
        value:
          type: string
          title: Value
          description: Value in wei as a string
        data:
          type: string
          title: Data
          description: Transaction data as hex string
        operation:
          $ref: '#/components/schemas/OperationType'
          description: Operation type (0=Call, 1=DelegateCall)
        safeTxGas:
          type: string
          title: Safetxgas
          description: Gas for the transaction
        baseGas:
          type: string
          title: Basegas
          description: Base gas costs
        gasPrice:
          type: string
          title: Gasprice
          description: Gas price
        gasToken:
          type: string
          title: Gastoken
          description: Token address for gas payment
        refundReceiver:
          type: string
          title: Refundreceiver
          description: Address to receive gas refund
        nonce:
          type: string
          title: Nonce
          description: Transaction nonce
      type: object
      required:
        - to
        - value
        - data
        - operation
        - safeTxGas
        - baseGas
        - gasPrice
        - gasToken
        - refundReceiver
        - nonce
      title: SafeTxMessage
      description: The message data for the transaction.
    EIP712DomainField:
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
      type: object
      required:
        - name
        - type
      title: EIP712DomainField
      description: A field in the EIP712Domain type definition.
    SafeTxField:
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
      type: object
      required:
        - name
        - type
      title: SafeTxField
      description: A field in the SafeTx type definition.
    OperationType:
      type: integer
      enum:
        - 0
        - 1
      title: OperationType
      description: Safe operation types.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Compass API Key. Get your key
        [here](https://www.compasslabs.ai/dashboard).

````