Handle ParaLens API Versioning and Schema Evolution

ParaLens uses a schema_version integer at the top of every TxReport. Currently 1. Clients should read this field and follow the guidance on this page to build integrations that continue working as the API evolves.

schema_version

Every TxReport includes schema_version as its first field:

{
  "schema_version": 1,
  ...
}

Check this value before parsing:

const report = await analyze(txHash);

if (report.schema_version !== 1) {
  console.warn(`Unexpected schema version: ${report.schema_version}`);
  // Fall back to a minimal display or prompt the user to refresh
}

A bump to schema_version signals a breaking structural change to the response shape. Additive changes (new fields, new enum values) do not bump the version.

Additive vs. Breaking Changes

Additive (non-breaking)

These changes will not break well-written clients and will not bump schema_version:

New top-level fields in TxReport
New intent_kind values
New motif.kind values
New economics.warnings string values
New position_effects.effect or .kind values
New optional sub-fields in any object

Breaking (version bump)

These changes will bump schema_version:

Removed fields
Renamed fields
Changed field types
Changed response shape at the top level
Removed enum values your code may depend on

Client Resilience Rules

Follow these rules to write a client that degrades gracefully rather than breaking on additive changes:

Check schema_version on startup

Read and validate schema_version as the first step in your parsing logic. Log or alert when it changes.

Treat unknown intent_kind as UnknownComplexFlow

Never throw on an unrecognized intent_kind. Always provide a fallback:

function getLayout(intentKind: string) {
  return layoutMap[intentKind] ?? 'fallback';
}

See Dashboard Layouts for a full layout switch.

Treat unknown motif.kind as opaque

Motif kinds are structural evidence labels. If you encounter an unknown kind, skip it or show it as a raw label — do not fail.

Treat missing optional fields as null/undefined

Many fields are optional. Accessing report.classification.actor may return null. Use optional chaining or null checks throughout.

const actor = report.classification?.actor ?? report.tx.signer;

Never hard-fail on unknown warning strings

economics.warnings is a string array. New warning codes may be added. Handle known warnings explicitly and log or ignore the rest.

for (const warning of report.economics.warnings) {
  if (warning === 'IntentActorDiffersFromSigner') {
    showActorWarning();
  } else {
    console.info('[ParaLens] Unknown warning:', warning);
  }
}

Always check DisplayMoney.available

Any field using the DisplayMoney shape (fee_usd, net_usd_before_gas, etc.) may have available: false. Never render the text value without checking first.

function renderMoney(money: DisplayMoney): string {
  return money.available ? money.text : money.reason ?? '—';
}

TypeScript Type Safety

Avoid strict union types for intent_kind in your client — this causes TypeScript errors when new values appear:

// ❌ Breaks when a new intent_kind is added
type IntentKind = 'Swap' | 'AggregatedSwap' | 'Arbitrage';

// ✅ Accepts any value; document known values in a comment
type IntentKind = string; // Known values: 'Swap', 'AggregatedSwap', 'Arbitrage', ...

For autocomplete benefits without the fragility, use a const object as a reference alongside a string type:

export const INTENT_KINDS = {
  Swap: 'Swap',
  AggregatedSwap: 'AggregatedSwap',
  Arbitrage: 'Arbitrage',
  AtomicArbitrage: 'AtomicArbitrage',
  // ... etc.
} as const;

export type IntentKind = string; // Use INTENT_KINDS constants for comparisons

Staying Up to Date

Monitor this documentation for schema change announcements.
Pin your integration on schema_version: 1 and alert when the value changes.
Treat any new intent_kind or motif.kind values in production logs as signal to update your layout mappings.

Because confirmed Ethereum transactions are immutable, you can cache TxReport responses indefinitely by tx hash. A schema version upgrade only affects new API calls — cached responses from the old version remain valid for their original schema.

Get Started

Use Cases

Integration Guides

Help

Handle ParaLens API Versioning and Schema Evolution

schema_version

Additive vs. Breaking Changes

Additive (non-breaking)

Breaking (version bump)

Client Resilience Rules

TypeScript Type Safety

Staying Up to Date

​schema_version

​Additive vs. Breaking Changes

Additive (non-breaking)

Breaking (version bump)

​Client Resilience Rules

​TypeScript Type Safety

​Staying Up to Date

schema_version

Additive vs. Breaking Changes

Client Resilience Rules

TypeScript Type Safety

Staying Up to Date