Portfolio Analysis API

Overview

The Portfolio Analysis API provides stateless analysis tools for yield portfolio construction. Use it to inspect a single instrument, score a weighted allocation book, compare two books, or simulate historical compounded yield at fixed weights. All endpoints are under the global /api/v1 prefix and use x-api-key authentication.

Portfolio analysis APY values are returned as percentages. For example, 5.2 means 5.2% APY.

These endpoints describe yield history and concentration. They do not model depeg risk, protocol failure, principal loss, gas, bridge costs, or future APY changes.

Allocation Format

Portfolio endpoints accept allocations as instrument IDs with weights in basis points.

{
  "allocations": [
    {
      "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
      "weightBps": 6000
    },
    {
      "instrumentId": "0x00002105e1d832a44e229e784c3d4afba9a1ca44a288e34f7e5ddcba23155adc",
      "weightBps": 4000
    }
  ]
}

Weights should normally sum to 10000. If some instruments cannot be resolved, the backend excludes them, returns a warning, and normalizes over the resolved positions.

Analyze Instrument

GET /instruments/:instrumentId/analysis Return a per-instrument analyst card with current yield, APY stability, liquidity, price-risk flag, and data-derived tier.

Request

curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/instruments/0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b/analysis"

Path Parameters

Parameter	Type	Required	Description
`instrumentId`	string	Yes	Public instrument ID, as bytes32 hex

Response

{
  "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Aave V3 USDC lending pool on Base",
  "protocol": "Aave",
  "chainId": 8453,
  "yield": {
    "currentApyPct": 5.2,
    "apyMean30dPct": 5.05,
    "rewardSharePct": 3.85
  },
  "stability": {
    "coefficientOfVariation": 0.12,
    "yieldDrawdownPct": 0.42,
    "downsideFreqPct": 6.67,
    "trendPctPerWeek": 0.04,
    "historyDays": 180
  },
  "liquidity": {
    "tvlUsd": 1250000000,
    "lowLiquidity": false
  },
  "priceRisk": false,
  "tier": "Core",
  "headline": "Aave V3 USDC lending pool on Base: 5.2% APY, Core tier, CV 0.12 over 180d, 4% reward-driven.",
  "caveats": [
    "APY mean-reverts and incentive APY decays; high current APY is not durable yield."
  ]
}

Key Response Fields

Field	Type	Description
`yield.currentApyPct`	number	Latest instrument APY, as a percentage
`yield.apyMean30dPct`	number	Current 30-day mean APY from synced metrics
`yield.rewardSharePct`	number	Share of current APY driven by rewards, as a percentage
`stability.coefficientOfVariation`	number	APY standard deviation divided by mean; lower is steadier
`stability.yieldDrawdownPct`	number	Worst peak-to-trough drop in APY over the lookback window
`stability.downsideFreqPct`	number	Percent of days below the configured downside APY target
`stability.trendPctPerWeek`	number	Recent APY trend in percentage points per week
`liquidity.lowLiquidity`	boolean	`true` when TVL is below the configured low-liquidity floor
`priceRisk`	boolean	`true` for instruments whose NAV can fall, such as non-stablecoin instruments
`tier`	string	Data-derived tier: `Core`, `Yield`, or `Frontier`
`headline`	string	One-line summary of the analysis
`caveats`	string[]	Risk and methodology caveats that should be shown to users

Analyze Portfolio

POST /portfolios/analyze Score a weighted allocation book across yield, stability, diversification, concentration, structural tail risk, and tier sleeves.

Request

curl -X POST "https://api.1tx.fi/api/v1/portfolios/analyze" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "allocations": [
      {
        "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
        "weightBps": 6000
      },
      {
        "instrumentId": "0x00002105e1d832a44e229e784c3d4afba9a1ca44a288e34f7e5ddcba23155adc",
        "weightBps": 4000
      }
    ]
  }'

Request Body

Field	Type	Required	Description
`allocations`	array	Yes	One or more allocation objects
`allocations[].instrumentId`	string	Yes	Public instrument ID, as bytes32 hex
`allocations[].weightBps`	number	Yes	Allocation weight in basis points, from `0` to `10000`

Response

{
  "resolvedCount": 2,
  "warnings": [],
  "yield": {
    "netApyPct": 5.04,
    "grossApyPct": 5.04,
    "weightedApyMean30dPct": 4.91
  },
  "stability": {
    "coefficientOfVariation": 0.14,
    "yieldDrawdownPct": 0.51,
    "daysWithinBandPct": 88.33,
    "coveragePct": 100
  },
  "diversification": {
    "effectivePositions": 1.92,
    "effectiveIndependentBets": 1.74,
    "avgPairwiseCorrelation": 0.21,
    "coverageBps": 10000
  },
  "concentration": {
    "effectivePositions": 1.92,
    "hhi": 0.52,
    "topWeightBps": 6000,
    "byProtocol": {
      "items": [
        { "key": "Aave", "weightBps": 6000 },
        { "key": "Morpho", "weightBps": 4000 }
      ],
      "effectiveGroups": 1.92,
      "topWeightBps": 6000
    },
    "byChain": {
      "items": [{ "key": "Base", "weightBps": 10000 }],
      "effectiveGroups": 1,
      "topWeightBps": 10000
    },
    "byAssetCategory": {
      "items": [{ "key": "USD", "weightBps": 10000 }],
      "effectiveGroups": 1,
      "topWeightBps": 10000
    },
    "byUnderlying": {
      "items": [{ "key": "USDC", "weightBps": 10000 }],
      "effectiveGroups": 1,
      "topWeightBps": 10000
    },
    "limitFlags": []
  },
  "tail": {
    "oneFailureCostBps": 6000,
    "sleeveWipeBps": 10000,
    "worstProtocolBps": 6000,
    "worstAssetCategoryBps": 10000,
    "weightedRewardSharePct": 4.6,
    "liquidity": {
      "weightedTvlUsd": 884000000,
      "illiquidWeightBps": 0
    }
  },
  "tranches": [
    {
      "name": "Core",
      "instrumentIds": [
        "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b"
      ],
      "weightBps": 6000,
      "netApyPct": 5.2,
      "stabilityCV": 0.12,
      "rationale": "High TVL, low yield variability, and low reward dependence."
    }
  ],
  "headline": "2 positions at 5.04% blended APY, behaving like ~1.74 independent bets.",
  "caveats": [
    "netApy is currently gross; no gas / bridge / fee model yet."
  ]
}

Key Response Fields

Field	Type	Description
`resolvedCount`	number	Number of requested instruments found and scored
`warnings`	string[]	Missing instruments or low-confidence analysis warnings
`yield.netApyPct`	number	Weighted portfolio APY, currently gross of costs
`stability.coefficientOfVariation`	number	CV of the blended portfolio APY series
`stability.coveragePct`	number	Percent of blended-history days with enough data coverage
`diversification.effectivePositions`	number	Inverse-Herfindahl effective number of positions
`diversification.effectiveIndependentBets`	number \| null	Correlation-adjusted effective bets, or `null` when history is thin
`concentration.limitFlags`	array	Concentration cap breaches by position, protocol, chain, asset category, or underlying
`tail.oneFailureCostBps`	number	Worst single-position failure exposure in basis points
`tail.weightedRewardSharePct`	number	Weighted share of APY from incentives
`tranches`	array	Portfolio sleeves grouped by `Core`, `Yield`, and `Frontier` tiers
`headline`	string	One-line summary of the scorecard
`caveats`	string[]	Risk and methodology caveats that should be shown to users

Compare Allocations

POST /portfolios/compare Compare two allocation books and return before/after analyses with metric and factor-exposure deltas.

Request

curl -X POST "https://api.1tx.fi/api/v1/portfolios/compare" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "before": [
      {
        "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
        "weightBps": 10000
      }
    ],
    "after": [
      {
        "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
        "weightBps": 6000
      },
      {
        "instrumentId": "0x00002105e1d832a44e229e784c3d4afba9a1ca44a288e34f7e5ddcba23155adc",
        "weightBps": 4000
      }
    ]
  }'

Request Body

Field	Type	Required	Description
`before`	array	Yes	Allocation book before the proposed change
`after`	array	Yes	Allocation book after the proposed change
`before[].instrumentId` / `after[].instrumentId`	string	Yes	Public instrument ID, as bytes32 hex
`before[].weightBps` / `after[].weightBps`	number	Yes	Allocation weight in basis points

Response

{
  "before": {
    "resolvedCount": 1,
    "yield": { "netApyPct": 5.2, "grossApyPct": 5.2, "weightedApyMean30dPct": 5.05 },
    "headline": "1 positions at 5.2% blended APY, behaving like ~1 independent bet.",
    "warnings": [],
    "caveats": []
  },
  "after": {
    "resolvedCount": 2,
    "yield": { "netApyPct": 5.04, "grossApyPct": 5.04, "weightedApyMean30dPct": 4.91 },
    "headline": "2 positions at 5.04% blended APY, behaving like ~1.74 independent bets.",
    "warnings": [],
    "caveats": []
  },
  "deltas": {
    "netApyPct": { "before": 5.2, "after": 5.04, "delta": -0.16 },
    "effectivePositions": { "before": 1, "after": 1.92, "delta": 0.92 },
    "oneFailureCostBps": { "before": 10000, "after": 6000, "delta": -4000 }
  },
  "factorDeltas": [
    {
      "dimension": "protocol",
      "key": "Morpho",
      "beforeBps": 0,
      "afterBps": 4000,
      "deltaBps": 4000
    }
  ],
  "headline": "Net APY -0.16pp, independent bets 1 to 1.74, CV +0.01."
}

The before and after objects use the same full response shape as Analyze Portfolio. The example above is shortened for readability.

Simulate History

POST /portfolios/simulate Compound the realized blended APY history for a fixed-weight allocation book. This is descriptive and should not be treated as a forecast.

Request

curl -X POST "https://api.1tx.fi/api/v1/portfolios/simulate" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "allocations": [
      {
        "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
        "weightBps": 6000
      },
      {
        "instrumentId": "0x00002105e1d832a44e229e784c3d4afba9a1ca44a288e34f7e5ddcba23155adc",
        "weightBps": 4000
      }
    ],
    "lookbackDays": 180,
    "principalUsd": 10000,
    "benchmark": "USD_INDEX"
  }'

Request Body

Field	Type	Required	Description
`allocations`	array	Yes	Allocation book to simulate
`lookbackDays`	number	No	History window in days, from `7` to `1095`. Defaults to backend configuration
`principalUsd`	number	No	Starting principal in USD. Defaults to backend configuration
`benchmark`	string	No	Instrument ID to benchmark against, or `USD_INDEX` for a TVL-weighted stablecoin market benchmark. If omitted, a flat-rate benchmark is used

Response

{
  "resolvedCount": 2,
  "warnings": [],
  "lookbackDays": 180,
  "principalUsd": 10000,
  "finalValueUsd": 10248.31,
  "realizedReturnPct": 2.48,
  "annualizedPct": 5.08,
  "blendedApyVolPct": 0.38,
  "maxYieldDrawdownPct": 0.51,
  "benchmark": {
    "kind": "index",
    "label": "USD market avg (18 markets)",
    "finalValueUsd": 10212.44,
    "annualizedPct": 4.34,
    "outperformancePct": 0.74
  },
  "coveragePct": 100,
  "daysSimulated": 180,
  "headline": "2.48% over 180d (5.08% annualized), +0.74pp vs USD market avg (18 markets).",
  "caveats": [
    "Past correlation does not predict future correlation."
  ]
}

Response Fields

Field	Type	Description
`finalValueUsd`	number	Ending principal after compounding realized daily APY history
`realizedReturnPct`	number	Total simulated return over the simulated days
`annualizedPct`	number	Annualized rate implied by the simulation
`blendedApyVolPct`	number	Standard deviation of the blended daily APY series
`maxYieldDrawdownPct`	number	Worst peak-to-trough APY drawdown in the blended series
`benchmark.kind`	string	`flatRate`, `instrument`, or `index`
`benchmark.outperformancePct`	number	Portfolio annualized APY minus benchmark annualized APY, in percentage points
`coveragePct`	number	Percent of blended-history days with enough data coverage
`daysSimulated`	number	Number of days with usable blended history
`headline`	string	One-line summary of the simulation
`caveats`	string[]	Risk and methodology caveats that should be shown to users

TypeScript Example

const BASE_URL = 'https://api.1tx.fi/api/v1';
const API_KEY = process.env['1TX_API_KEY'];

async function analyzePortfolio(allocations: Array<{ instrumentId: string; weightBps: number }>) {
  const response = await fetch(`${BASE_URL}/portfolios/analyze`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY ?? '',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ allocations }),
  });

  if (!response.ok) {
    throw new Error(`Failed to analyze portfolio: ${response.status}`);
  }

  return response.json();
}

const analysis = await analyzePortfolio([
  {
    instrumentId: '0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b',
    weightBps: 10000,
  },
]);

console.log(analysis.headline);

API Documentation

Overview

Allocation Format

Analyze Instrument

Request

Path Parameters

Response

Key Response Fields

Analyze Portfolio

Request

Request Body

Response

Key Response Fields

Compare Allocations

Request

Request Body

Response

Simulate History

Request

Request Body

Response

Response Fields

TypeScript Example

Next Steps

Instruments API

Yield Index API

​Overview

​Allocation Format

​Analyze Instrument

​Request

​Path Parameters

​Response

​Key Response Fields

​Analyze Portfolio

​Request

​Request Body

​Response

​Key Response Fields

​Compare Allocations

​Request

​Request Body

​Response

​Simulate History

​Request

​Request Body

​Response

​Response Fields

​TypeScript Example

​Next Steps

Instruments API

Yield Index API

Overview

Allocation Format

Analyze Instrument

Request

Path Parameters

Response

Key Response Fields

Analyze Portfolio

Request

Request Body

Response

Key Response Fields

Compare Allocations

Request

Request Body

Response

Simulate History

Request

Request Body

Response

Response Fields

TypeScript Example

Next Steps