Skip to content
ChordChordChord Docs

Plan a position

GET
/lp/plan
curl --request GET \
  --url 'https://api.getchord.xyz/v1/lp/plan?chain=5042&token=example&amountUsd=1000&days=7'

Range bands for a token from its own volatility (tight / balanced / wide, with the share of the last seven days each range would have stayed inside) and each profile backtested on Chord’s candles against holding — fees, impermanent loss, exits, time in range. Needs at least 24 hourly candles and an anchored pool (404 NOT_ENOUGH_HISTORY otherwise). young: true means under two days of candles — the bands are a launch’s noise.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
chain
required
integer
Allowed values: 5042 4663 143

Chain id: 5042 Arc · 4663 Robinhood Chain · 143 Monad.

token
required

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
amountUsd
number
default: 1000 >= 1
days
integer
default: 7 >= 1 <= 30

Backtest window.

pool

A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id.

string
/^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/

Pin a pool; default = the token’s best anchored pool.

Responses

Section titled “ Responses ”

200

Section titled “200”
Media typeapplication/json
object
chain
integer
token

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
amountUsd
number
days
integer
bands
object
priceUsd
number
hourlyVolPct
number
dailyVolPct
number
candles
integer
young
boolean
profiles
Array<object>
object
profile
string
Allowed values: tight balanced wide
horizonHours
integer
lower
number
upper
number
widthPct
number
last7dInsidePct
number
histogram

Where the price spent its hours.

Array<object>
object
lo
number
hi
number
hours
integer
sims
Array<object>
object
profile
string
lower
number
upper
number
sim

One range, backtested on Chord’s own candles and the pool’s real fee tier.

object
pool

A pool: a 20-byte contract address (V2 / V3) or a 32-byte Uniswap V4 pool id.

string
/^0x([a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/
dex
string
feeBps
number | null
tvlUsd
number | null
days
integer
hours

Candles replayed.

integer
hoursInRange
integer
inRangePct
number
exits

Times the price left the range.

integer
lower
number
upper
number
unreliable

Why the number should not be trusted, when it should not.

string | null
entryPrice
number
exitPrice
number
priceChangePct
number
feesUsd
number
lpValueEndUsd
number
holdValueEndUsd
number
ilUsd

Impermanent loss (negative = loss).

number
netVsHoldUsd
number
totalReturnUsd
number
totalReturnPct
number
feeAprPct
number
capitalEfficiency

Versus full range.

number
shareOfPoolPct
number
note
string
updatedAt

Unix time, milliseconds — when the server built this answer.

integer
Example
{
  "chain": 5042,
  "token": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0",
  "amountUsd": 1000,
  "days": 7,
  "bands": {
    "priceUsd": 80418.25,
    "hourlyVolPct": 0.44,
    "dailyVolPct": 2.1,
    "candles": 104,
    "young": false,
    "profiles": [
      {
        "profile": "tight",
        "horizonHours": 24,
        "lower": 78711.94,
        "upper": 82161.56,
        "widthPct": 2.2,
        "last7dInsidePct": 42
      },
      {
        "profile": "balanced",
        "horizonHours": 72,
        "lower": 76059.95,
        "upper": 85026.29,
        "widthPct": 5.7,
        "last7dInsidePct": 82
      }
    ],
    "histogram": [
      {
        "lo": 73301.06,
        "hi": 73799.8,
        "hours": 1
      },
      {
        "lo": 73799.8,
        "hi": 74301.94,
        "hours": 0
      }
    ]
  },
  "sims": [
    {
      "profile": "tight",
      "lower": 78711.94,
      "upper": 82161.56,
      "sim": {
        "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41",
        "dex": "uniswap_v3",
        "feeBps": 1,
        "tvlUsd": 11239238.75,
        "days": 7,
        "hours": 104,
        "hoursInRange": 1,
        "inRangePct": 1,
        "exits": 1,
        "lower": 71745.77,
        "upper": 74890.09,
        "unreliable": null,
        "entryPrice": 73301.06,
        "exitPrice": 80418.25,
        "priceChangePct": 9.7,
        "feesUsd": 0.01,
        "lpValueEndUsd": 1005.39,
        "holdValueEndUsd": 1048.55,
        "ilUsd": -43.16,
        "netVsHoldUsd": -43.15,
        "totalReturnUsd": 5.4,
        "totalReturnPct": 0.54,
        "feeAprPct": 0.1,
        "capitalEfficiency": 50,
        "shareOfPoolPct": 0.443,
        "note": "Backtest on the last 7 days of Chord's own candles and this pool's hourly volume at today's TVL — what would have happened, not what will."
      }
    },
    {
      "profile": "balanced",
      "lower": 76059.95,
      "upper": 85026.29,
      "sim": {
        "pool": "0x82916bee18fcef517b26c72d7cb5f13694e1db41",
        "dex": "uniswap_v3",
        "feeBps": 1,
        "tvlUsd": 11239238.75,
        "days": 7,
        "hours": 104,
        "hoursInRange": 53,
        "inRangePct": 51,
        "exits": 1,
        "lower": 69328.48,
        "upper": 77501.28,
        "unreliable": null,
        "entryPrice": 73301.06,
        "exitPrice": 80418.25,
        "priceChangePct": 9.7,
        "feesUsd": 3.03,
        "lpValueEndUsd": 1014.13,
        "holdValueEndUsd": 1048.55,
        "ilUsd": -34.42,
        "netVsHoldUsd": -31.39,
        "totalReturnUsd": 17.16,
        "totalReturnPct": 1.72,
        "feeAprPct": 15.8,
        "capitalEfficiency": 36.4,
        "shareOfPoolPct": 0.323,
        "note": "Backtest on the last 7 days of Chord's own candles and this pool's hourly volume at today's TVL — what would have happened, not what will."
      }
    }
  ],
  "updatedAt": 1789891866541
}

400

Section titled “400”

Invalid parameters — error names the check that failed (INVALID_PARAMS, BAD_ADDRESS, BAD_LIMIT, BAD_HOURS, …).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

404

Section titled “404”

Nothing at this identity (NOT_FOUND, UNKNOWN_TOKEN, NO_ROUTE).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}