Python (SDK)

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)

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();

curl --request POST \
  --url https://api.compasslabs.ai/v2/risk_yield/mint \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "owner": "0x06A9aF046187895AcFc7258450B15397CAc67400",
  "chain": "robinhood",
  "pool": {
    "pool_id": 1
  },
  "range": {
    "type": "symmetric_pct",
    "width_pct": "30"
  },
  "deposit": {
    "amount0": "100",
    "amount1": "0.04",
    "type": "both"
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    owner: '0x06A9aF046187895AcFc7258450B15397CAc67400',
    chain: 'robinhood',
    pool: {pool_id: 1},
    range: {type: 'symmetric_pct', width_pct: '30'},
    deposit: {amount0: '100', amount1: '0.04', type: 'both'}
  })
};

fetch('https://api.compasslabs.ai/v2/risk_yield/mint', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.compasslabs.ai/v2/risk_yield/mint",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'owner' => '0x06A9aF046187895AcFc7258450B15397CAc67400',
    'chain' => 'robinhood',
    'pool' => [
        'pool_id' => 1
    ],
    'range' => [
        'type' => 'symmetric_pct',
        'width_pct' => '30'
    ],
    'deposit' => [
        'amount0' => '100',
        'amount1' => '0.04',
        'type' => 'both'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.compasslabs.ai/v2/risk_yield/mint"

	payload := strings.NewReader("{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"robinhood\",\n  \"pool\": {\n    \"pool_id\": 1\n  },\n  \"range\": {\n    \"type\": \"symmetric_pct\",\n    \"width_pct\": \"30\"\n  },\n  \"deposit\": {\n    \"amount0\": \"100\",\n    \"amount1\": \"0.04\",\n    \"type\": \"both\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.compasslabs.ai/v2/risk_yield/mint")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"robinhood\",\n  \"pool\": {\n    \"pool_id\": 1\n  },\n  \"range\": {\n    \"type\": \"symmetric_pct\",\n    \"width_pct\": \"30\"\n  },\n  \"deposit\": {\n    \"amount0\": \"100\",\n    \"amount1\": \"0.04\",\n    \"type\": \"both\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.compasslabs.ai/v2/risk_yield/mint")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"robinhood\",\n  \"pool\": {\n    \"pool_id\": 1\n  },\n  \"range\": {\n    \"type\": \"symmetric_pct\",\n    \"width_pct\": \"30\"\n  },\n  \"deposit\": {\n    \"amount0\": \"100\",\n    \"amount1\": \"0.04\",\n    \"type\": \"both\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "transaction": {
    "chainId": "0x2105",
    "data": "0x1688f0b900000000000000000000000029fcb43b46531bca003ddc8fcb67ffe91900c762000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000675f4a3d",
    "from": "0x4A83b4413CF41C3244027e1590E35a0F48403F0c",
    "gas": "0x7a120",
    "maxFeePerGas": "0x59682f00",
    "maxPriorityFeePerGas": "0x3b9aca00",
    "nonce": "0x5",
    "to": "0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67",
    "value": "0x0"
  },
  "position_id": 123,
  "range": {
    "tick_lower": 123,
    "tick_upper": 123,
    "price_lower": "<string>",
    "price_upper": "<string>",
    "width_lower_pct": "<string>",
    "width_upper_pct": "<string>",
    "is_full_range": true
  },
  "plan": {
    "amount0_desired": "<string>",
    "amount1_desired": "<string>",
    "amount0_min": "<string>",
    "amount1_min": "<string>",
    "leftover0": "0",
    "leftover1": "0",
    "swap": {
      "token_in": "<string>",
      "token_out": "<string>",
      "amount_in": "<string>",
      "amount_out_quoted": "<string>",
      "amount_out_min": "<string>",
      "price_impact_pct": "<string>",
      "pool_fee_ppm": 123
    }
  },
  "expected_liquidity": "<string>",
  "liquidity_removed": "<string>",
  "amount0_min": "<string>",
  "amount1_min": "<string>",
  "steps": [
    {
      "kind": "APPROVE",
      "description": "<string>",
      "contract": "<string>",
      "token": "<string>",
      "amount": "<string>"
    }
  ],
  "simulation": {
    "ok": true,
    "error": "<string>",
    "gas_used": 123
  },
  "warnings": [
    "<string>"
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Risk Yield

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.

POST

risk_yield

mint

Python (SDK)

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)

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();

curl --request POST \
  --url https://api.compasslabs.ai/v2/risk_yield/mint \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "owner": "0x06A9aF046187895AcFc7258450B15397CAc67400",
  "chain": "robinhood",
  "pool": {
    "pool_id": 1
  },
  "range": {
    "type": "symmetric_pct",
    "width_pct": "30"
  },
  "deposit": {
    "amount0": "100",
    "amount1": "0.04",
    "type": "both"
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    owner: '0x06A9aF046187895AcFc7258450B15397CAc67400',
    chain: 'robinhood',
    pool: {pool_id: 1},
    range: {type: 'symmetric_pct', width_pct: '30'},
    deposit: {amount0: '100', amount1: '0.04', type: 'both'}
  })
};

fetch('https://api.compasslabs.ai/v2/risk_yield/mint', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.compasslabs.ai/v2/risk_yield/mint",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'owner' => '0x06A9aF046187895AcFc7258450B15397CAc67400',
    'chain' => 'robinhood',
    'pool' => [
        'pool_id' => 1
    ],
    'range' => [
        'type' => 'symmetric_pct',
        'width_pct' => '30'
    ],
    'deposit' => [
        'amount0' => '100',
        'amount1' => '0.04',
        'type' => 'both'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.compasslabs.ai/v2/risk_yield/mint"

	payload := strings.NewReader("{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"robinhood\",\n  \"pool\": {\n    \"pool_id\": 1\n  },\n  \"range\": {\n    \"type\": \"symmetric_pct\",\n    \"width_pct\": \"30\"\n  },\n  \"deposit\": {\n    \"amount0\": \"100\",\n    \"amount1\": \"0.04\",\n    \"type\": \"both\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.compasslabs.ai/v2/risk_yield/mint")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"robinhood\",\n  \"pool\": {\n    \"pool_id\": 1\n  },\n  \"range\": {\n    \"type\": \"symmetric_pct\",\n    \"width_pct\": \"30\"\n  },\n  \"deposit\": {\n    \"amount0\": \"100\",\n    \"amount1\": \"0.04\",\n    \"type\": \"both\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.compasslabs.ai/v2/risk_yield/mint")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"owner\": \"0x06A9aF046187895AcFc7258450B15397CAc67400\",\n  \"chain\": \"robinhood\",\n  \"pool\": {\n    \"pool_id\": 1\n  },\n  \"range\": {\n    \"type\": \"symmetric_pct\",\n    \"width_pct\": \"30\"\n  },\n  \"deposit\": {\n    \"amount0\": \"100\",\n    \"amount1\": \"0.04\",\n    \"type\": \"both\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "transaction": {
    "chainId": "0x2105",
    "data": "0x1688f0b900000000000000000000000029fcb43b46531bca003ddc8fcb67ffe91900c762000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000675f4a3d",
    "from": "0x4A83b4413CF41C3244027e1590E35a0F48403F0c",
    "gas": "0x7a120",
    "maxFeePerGas": "0x59682f00",
    "maxPriorityFeePerGas": "0x3b9aca00",
    "nonce": "0x5",
    "to": "0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67",
    "value": "0x0"
  },
  "position_id": 123,
  "range": {
    "tick_lower": 123,
    "tick_upper": 123,
    "price_lower": "<string>",
    "price_upper": "<string>",
    "width_lower_pct": "<string>",
    "width_upper_pct": "<string>",
    "is_full_range": true
  },
  "plan": {
    "amount0_desired": "<string>",
    "amount1_desired": "<string>",
    "amount0_min": "<string>",
    "amount1_min": "<string>",
    "leftover0": "0",
    "leftover1": "0",
    "swap": {
      "token_in": "<string>",
      "token_out": "<string>",
      "amount_in": "<string>",
      "amount_out_quoted": "<string>",
      "amount_out_min": "<string>",
      "price_impact_pct": "<string>",
      "pool_fee_ppm": 123
    }
  },
  "expected_liquidity": "<string>",
  "liquidity_removed": "<string>",
  "amount0_min": "<string>",
  "amount1_min": "<string>",
  "steps": [
    {
      "kind": "APPROVE",
      "description": "<string>",
      "contract": "<string>",
      "token": "<string>",
      "amount": "<string>"
    }
  ],
  "simulation": {
    "ok": true,
    "error": "<string>",
    "gas_used": 123
  },
  "warnings": [
    "<string>"
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

x-api-key

string

header

required

Your Compass API Key. Get your key here.

Body

application/json

Open a new position.

owner

string

default:0x06A9aF046187895AcFc7258450B15397CAc67400

required

The wallet that owns the Risk Yield Account.

Example:

"0x06A9aF046187895AcFc7258450B15397CAc67400"

pool

PoolSelector · object

required

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.

Show child attributes

Example:

{ "pool_id": 1 }

range

SymmetricRange · object

required

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.

SymmetricRange
TickRange
PriceRange
FullRange

Show child attributes

Example:

{
  "type": "symmetric_pct",
  "width_pct": "30"
}

deposit

BothSidesDeposit · object

required

Explicit amounts of each token.

BothSidesDeposit
SingleSidedDeposit
UsdDeposit

Show child attributes

Example:

{
  "amount0": "100",
  "amount1": "0.04",
  "type": "both"
}

chain

enum<string>

default:robinhood

Risk Yield is available on Robinhood Chain only.

Available options:

robinhood

Example:

"robinhood"

gas_sponsorship

boolean

default:false

Return EIP-712 typed data for the owner to sign instead of a transaction, so a sponsor can broadcast it.

preview

boolean

default:false

Return the plan and its simulation without building a transaction. Nothing is signed and nothing can be broadcast.

slippage_pct

default:0.5

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.

Required range: 0 < x <= 10

deadline_seconds

integer

default:300

How long the transaction stays valid once built.

Required range: 30 <= x <= 3600

recipient

string | null

Who receives the position NFT. Defaults to the Risk Yield Account, which is what makes it manageable through this API.

Response

Successful Response

The shape every liquidity-changing endpoint returns.

transaction

UnsignedTransaction · object | null

Show child attributes

Example:

{
  "chainId": "0x2105",
  "data": "0x1688f0b900000000000000000000000029fcb43b46531bca003ddc8fcb67ffe91900c762000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000675f4a3d",
  "from": "0x4A83b4413CF41C3244027e1590E35a0F48403F0c",
  "gas": "0x7a120",
  "maxFeePerGas": "0x59682f00",
  "maxPriorityFeePerGas": "0x3b9aca00",
  "nonce": "0x5",
  "to": "0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67",
  "value": "0x0"
}

position_id

integer | null

range

ResolvedRange · object | null

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.

Show child attributes

plan

DepositPlan · object | null

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.

Show child attributes

expected_liquidity

string | null

liquidity_removed

string | null

amount0_min

string | null

amount1_min

string | null

steps

PlanStep · object[]

Show child attributes

simulation

Simulation · object | null

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.

Show child attributes

warnings

string[]