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

# Open a position

> Provide liquidity to a pool over a price range.

The range you ask for is not quite the range you get: ticks are discrete, so
a 30% band becomes the usable ticks that bracket it — snapped outward, never
inward, because a position that stops earning sooner than you expected is
the worse surprise. The `range` in the response is what will actually be
opened.

A range also fixes the proportion of the two assets, so a deposit rarely
uses all of both. What does not fit is reported as `leftover` and stays in
your account rather than being quietly swept.

Set `preview` to see the plan and its simulation without building anything.



## OpenAPI

````yaml /v2/combined_spec.json post /v2/risk_yield/mint
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/risk_yield/mint:
    post:
      tags:
        - Risk Yield
      summary: Open a position
      description: >-
        Provide liquidity to a pool over a price range.


        The range you ask for is not quite the range you get: ticks are
        discrete, so

        a 30% band becomes the usable ticks that bracket it — snapped outward,
        never

        inward, because a position that stops earning sooner than you expected
        is

        the worse surprise. The `range` in the response is what will actually be

        opened.


        A range also fixes the proportion of the two assets, so a deposit rarely

        uses all of both. What does not fit is reported as `leftover` and stays
        in

        your account rather than being quietly swept.


        Set `preview` to see the plan and its simulation without building
        anything.
      operationId: v2_risk_yield_mint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskYieldMintRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskYieldLiquidityResponse'
        '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.risk_yield.risk_yield_mint(owner="0x06A9aF046187895AcFc7258450B15397CAc67400", pool={
                    "pool_id": 1,
                }, range={
                    "type": "symmetric_pct",
                    "width_pct": "30",
                }, deposit={
                    "type": "both",
                    "amount0": "100",
                    "amount1": "0.04",
                }, chain=models.RiskYieldMintRequestChain.ROBINHOOD, gas_sponsorship=False, preview=False, slippage_pct="0.5", deadline_seconds=300)

                # 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.riskYield.riskYieldMint({
                owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
                chain: "robinhood",
                pool: {
                  poolId: 1,
                },
                range: {
                  type: "symmetric_pct",
                  widthPct: "30",
                },
                deposit: {
                  type: "both",
                  amount0: "100",
                  amount1: "0.04",
                },
              });

              console.log(result);
            }

            run();
components:
  schemas:
    RiskYieldMintRequest:
      properties:
        owner:
          type: string
          title: Owner
          description: The wallet that owns the Risk Yield Account.
          default: '0x06A9aF046187895AcFc7258450B15397CAc67400'
          examples:
            - '0x06A9aF046187895AcFc7258450B15397CAc67400'
        chain:
          type: string
          enum:
            - robinhood
          title: Chain
          description: Risk Yield is available on Robinhood Chain only.
          default: robinhood
          examples:
            - robinhood
        gas_sponsorship:
          type: boolean
          title: Gas Sponsorship
          description: >-
            Return EIP-712 typed data for the owner to sign instead of a
            transaction, so a sponsor can broadcast it.
          default: false
        preview:
          type: boolean
          title: Preview
          description: >-
            Return the plan and its simulation without building a transaction.
            Nothing is signed and nothing can be broadcast.
          default: false
        slippage_pct:
          anyOf:
            - type: number
              maximum: 10
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Slippage Pct
          description: >-
            How far the executed amounts may fall short of the quote before the
            transaction reverts. Memecoin pools move between the quote and the
            block that includes the transaction.
          default: '0.5'
        deadline_seconds:
          type: integer
          maximum: 3600
          minimum: 30
          title: Deadline Seconds
          description: How long the transaction stays valid once built.
          default: 300
        pool:
          $ref: '#/components/schemas/PoolSelector'
          default:
            pool_id: 1
          examples:
            - pool_id: 1
        range:
          oneOf:
            - $ref: '#/components/schemas/SymmetricRange'
            - $ref: '#/components/schemas/TickRange'
            - $ref: '#/components/schemas/PriceRange'
            - $ref: '#/components/schemas/FullRange'
          title: Range
          discriminator:
            propertyName: type
            mapping:
              full:
                $ref: '#/components/schemas/FullRange'
              prices:
                $ref: '#/components/schemas/PriceRange'
              symmetric_pct:
                $ref: '#/components/schemas/SymmetricRange'
              ticks:
                $ref: '#/components/schemas/TickRange'
          default:
            type: symmetric_pct
            width_pct: '30'
          examples:
            - type: symmetric_pct
              width_pct: '30'
        deposit:
          oneOf:
            - $ref: '#/components/schemas/BothSidesDeposit'
            - $ref: '#/components/schemas/SingleSidedDeposit'
            - $ref: '#/components/schemas/UsdDeposit'
          title: Deposit
          discriminator:
            propertyName: type
            mapping:
              both:
                $ref: '#/components/schemas/BothSidesDeposit'
              single:
                $ref: '#/components/schemas/SingleSidedDeposit'
              usd:
                $ref: '#/components/schemas/UsdDeposit'
          default:
            amount0: '100'
            amount1: '0.04'
            type: both
          examples:
            - amount0: '100'
              amount1: '0.04'
              type: both
        recipient:
          anyOf:
            - type: string
            - type: 'null'
          title: Recipient
          description: >-
            Who receives the position NFT. Defaults to the Risk Yield Account,
            which is what makes it manageable through this API.
      type: object
      required:
        - owner
        - pool
        - range
        - deposit
      title: RiskYieldMintRequest
      description: Open a new position.
      default:
        owner: '0x06A9aF046187895AcFc7258450B15397CAc67400'
        chain: robinhood
        pool:
          pool_id: 1
        range:
          type: symmetric_pct
          width_pct: '30'
        deposit:
          amount0: '100'
          amount1: '0.04'
          type: both
    RiskYieldLiquidityResponse:
      properties:
        transaction:
          anyOf:
            - $ref: '#/components/schemas/UnsignedTransaction'
            - type: 'null'
        position_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Position Id
        range:
          anyOf:
            - $ref: '#/components/schemas/ResolvedRange'
            - type: 'null'
        plan:
          anyOf:
            - $ref: '#/components/schemas/DepositPlan'
            - type: 'null'
        expected_liquidity:
          anyOf:
            - type: string
            - type: 'null'
          title: Expected Liquidity
        liquidity_removed:
          anyOf:
            - type: string
            - type: 'null'
          title: Liquidity Removed
        amount0_min:
          anyOf:
            - type: string
            - type: 'null'
          title: Amount0 Min
        amount1_min:
          anyOf:
            - type: string
            - type: 'null'
          title: Amount1 Min
        steps:
          items:
            $ref: '#/components/schemas/PlanStep'
          type: array
          title: Steps
        simulation:
          anyOf:
            - $ref: '#/components/schemas/Simulation'
            - type: 'null'
        warnings:
          items:
            type: string
          type: array
          title: Warnings
      type: object
      title: RiskYieldLiquidityResponse
      description: The shape every liquidity-changing endpoint returns.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PoolSelector:
      properties:
        pool_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Pool Id
          description: The pool's id, as returned by `GET /pools`.
        token0:
          anyOf:
            - type: string
            - type: 'null'
          title: Token0
          description: Lower-sorting token address.
        token1:
          anyOf:
            - type: string
            - type: 'null'
          title: Token1
          description: Higher-sorting token address.
        fee_ppm:
          anyOf:
            - type: integer
              maximum: 1000000
              minimum: 0
            - type: 'null'
          title: Fee Ppm
          description: Fee tier in hundredths of a bip (3000 = 0.30%).
        tick_spacing:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tick Spacing
          description: Required for v4, where it is part of the pool key.
        hooks:
          anyOf:
            - type: string
            - type: 'null'
          title: Hooks
          description: v4 hook address; part of the pool key.
        dex_version:
          $ref: '#/components/schemas/DexVersion'
          default: V3
      type: object
      title: PoolSelector
      description: >-
        Which pool, by id or by its key.


        A pool id is stable and is what the list endpoints return. The long form

        exists so a caller who knows the pair can address a pool without a
        lookup —

        on a chain minting twenty thousand pools a day, a client should not have
        to

        search for one it just created.
    SymmetricRange:
      properties:
        type:
          type: string
          const: symmetric_pct
          title: Type
          default: symmetric_pct
        width_pct:
          anyOf:
            - type: number
              maximum: 1000
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Width Pct
          description: Half-width either side of the current price, in percent.
          examples:
            - '30'
      type: object
      required:
        - width_pct
      title: SymmetricRange
      description: >-
        A range centred on the current price, given as a percentage either side.


        The usual way to ask for a position: narrow earns more fees per dollar
        while

        the price stays inside it, and stops earning entirely when it leaves.
    TickRange:
      properties:
        type:
          type: string
          const: ticks
          title: Type
          default: ticks
        tick_lower:
          type: integer
          title: Tick Lower
        tick_upper:
          type: integer
          title: Tick Upper
      type: object
      required:
        - tick_lower
        - tick_upper
      title: TickRange
      description: Exact tick bounds, for a caller who has already done the maths.
    PriceRange:
      properties:
        type:
          type: string
          const: prices
          title: Type
          default: prices
        price_lower:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Price Lower
        price_upper:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Price Upper
      type: object
      required:
        - price_lower
        - price_upper
      title: PriceRange
      description: Bounds as prices (token1 per token0, decimals-adjusted).
    FullRange:
      properties:
        type:
          type: string
          const: full
          title: Type
          default: full
      type: object
      title: FullRange
      description: 'The whole price range: never out of range, and never concentrated.'
    BothSidesDeposit:
      properties:
        type:
          type: string
          const: both
          title: Type
          default: both
        amount0:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount0
        amount1:
          anyOf:
            - type: number
              minimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount1
      type: object
      required:
        - amount0
        - amount1
      title: BothSidesDeposit
      description: Explicit amounts of each token.
    SingleSidedDeposit:
      properties:
        type:
          type: string
          const: single
          title: Type
          default: single
        token:
          type: string
          title: Token
        amount:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount
      type: object
      required:
        - token
        - amount
      title: SingleSidedDeposit
      description: >-
        One token, split to fit the range.


        A range needs both assets in a ratio the range itself determines, so
        this

        asks the API to solve for that ratio and swap the difference.
    UsdDeposit:
      properties:
        type:
          type: string
          const: usd
          title: Type
          default: usd
        value_usd:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Value Usd
      type: object
      required:
        - value_usd
      title: UsdDeposit
      description: |-
        A dollar figure, for analytics only.

        Enough to answer "what would this look like", not enough to build a
        transaction — the API will not choose which of your tokens to spend.
    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'
    ResolvedRange:
      properties:
        tick_lower:
          type: integer
          title: Tick Lower
        tick_upper:
          type: integer
          title: Tick Upper
        price_lower:
          type: string
          title: Price Lower
        price_upper:
          type: string
          title: Price Upper
        width_lower_pct:
          type: string
          title: Width Lower Pct
          description: How far below the current price the lower bound sits.
        width_upper_pct:
          type: string
          title: Width Upper Pct
        is_full_range:
          type: boolean
          title: Is Full Range
      type: object
      required:
        - tick_lower
        - tick_upper
        - price_lower
        - price_upper
        - width_lower_pct
        - width_upper_pct
        - is_full_range
      title: ResolvedRange
      description: >-
        A range after the API has snapped it to the pool's tick spacing.


        Returned because the range you asked for is rarely the range you get:
        ticks

        are discrete, and a 30% band becomes whichever usable ticks bracket it.
    DepositPlan:
      properties:
        amount0_desired:
          type: string
          title: Amount0 Desired
        amount1_desired:
          type: string
          title: Amount1 Desired
        amount0_min:
          type: string
          title: Amount0 Min
          description: The floor the transaction enforces after slippage.
        amount1_min:
          type: string
          title: Amount1 Min
        leftover0:
          type: string
          title: Leftover0
          default: '0'
        leftover1:
          type: string
          title: Leftover1
          default: '0'
        swap:
          anyOf:
            - $ref: '#/components/schemas/SwapPlan'
            - type: 'null'
          description: Present when one asset had to be traded for the other.
      type: object
      required:
        - amount0_desired
        - amount1_desired
        - amount0_min
        - amount1_min
      title: DepositPlan
      description: >-
        What will actually be deposited, and what is left over.


        A range fixes the ratio of the two assets, so a deposit rarely uses all
        of

        both. The leftovers are reported rather than silently swept: they stay
        in

        the account, and a caller who expected them to be used should know.
    PlanStep:
      properties:
        kind:
          $ref: '#/components/schemas/PlanStepKind'
        description:
          type: string
          title: Description
        contract:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract
        token:
          anyOf:
            - type: string
            - type: 'null'
          title: Token
        amount:
          anyOf:
            - type: string
            - type: 'null'
          title: Amount
      type: object
      required:
        - kind
        - description
      title: PlanStep
      description: >-
        One leg of a bundled transaction, in the order it executes.


        Every transact endpoint returns a single transaction; this is what is
        inside

        it, so a caller can show a person what they are about to sign.
    Simulation:
      properties:
        ok:
          type: boolean
          title: Ok
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        gas_used:
          anyOf:
            - type: integer
            - type: 'null'
          title: Gas Used
      type: object
      required:
        - ok
      title: Simulation
      description: >-
        The result of executing the transaction against current state.


        Meme tokens on this chain carry transfer taxes, blacklists and pause

        switches, none of which are visible from a pool's parameters. Simulating
        is

        the only way to find out before the owner signs.
    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
    DexVersion:
      type: string
      enum:
        - V3
        - V4
      title: DexVersion
      description: >-
        Which Uniswap deployment a pool belongs to.


        v3 pools hold their own tokens and pay LPs the fee tier. v4 pools live
        in a

        shared PoolManager and may route the fee through a hook, which is where
        the

        launchpad pools' zero LP yield comes from.
    SwapPlan:
      properties:
        token_in:
          type: string
          title: Token In
        token_out:
          type: string
          title: Token Out
        amount_in:
          type: string
          title: Amount In
        amount_out_quoted:
          type: string
          title: Amount Out Quoted
        amount_out_min:
          type: string
          title: Amount Out Min
          description: The floor the transaction enforces, after slippage.
        price_impact_pct:
          anyOf:
            - type: string
            - type: 'null'
          title: Price Impact Pct
        pool_fee_ppm:
          anyOf:
            - type: integer
            - type: 'null'
          title: Pool Fee Ppm
      type: object
      required:
        - token_in
        - token_out
        - amount_in
        - amount_out_quoted
        - amount_out_min
      title: SwapPlan
      description: The swap leg of an entry or a rebalance.
    PlanStepKind:
      type: string
      enum:
        - APPROVE
        - PERMIT2_APPROVE
        - SWAP
        - MINT
        - INCREASE
        - DECREASE
        - COLLECT
        - BURN
        - TRANSFER
      title: PlanStepKind
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Compass API Key. Get your key
        [here](https://www.compasslabs.ai/dashboard).

````