API versioning

​

Why versioning

​

Pinning a version

const res = await fetch("https://v1.orchestrator.rhinestone.dev/quotes", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
    "x-api-version": "2026-04.blanc",
  },
  body: JSON.stringify(payload),
});

​

Compatibility

​

What we can change without a new version

• New optional request fields
• New response fields
• New enum variants in responses (e.g. a new settlementLayer)
• New endpoints
• Widened request validation
• Changed default values

​

What your client must do

• Ignore unknown fields. If you use a strict JSON parser (Go’s DisallowUnknownFields, Rust serde(deny_unknown_fields), Jackson’s FAIL_ON_UNKNOWN_PROPERTIES), disable it for our responses.
• Handle unknown enum values gracefully. A switch on settlementLayer that throws on default will break the day we add a new one. Treat unknown values as “not supported by this client” and fall back.
• Don’t reconstruct EIP-712 types client-side. Forward the server’s typed data verbatim to wallet.signTypedData(). Hand-rolled type libraries break on additive schema changes.
• Treat quote 404s as normal. Quoted intents are stored server-side with a short TTL. If a quote expires or the quote store restarts, you’ll see 404 on submit. Re-quote — don’t retry the submit.
• Take routes[0] unless you have your own criteria. The array is server-ranked by a cost/speed tradeoff. Re-sorting client-side usually degrades route quality.

​

What triggers a new version

• Removing or renaming any field
• Adding a required request field
• Changing a field’s type
• Restructuring request or response shape
• Narrowing request validation
• Making a required response field optional or nullable
• Removing an endpoint

​

Deprecation lifecycle

​

Versions

​

2026-04.blanc

• Flat routes[] array. Each route carries its own intentId, cost, signData, and tokenRequirements (EOAs only — smart accounts handle approvals internally). Pre-ranked; routes[0] is recommended.
• CAIP-2 chain ids. Every chain id on the wire is now an eip155:<chainId> string — 1 becomes "eip155:1". Affects scalar fields, arrays, and chain-keyed maps. Path parameters are unchanged.
• EIP-712 typed data in the response. Forward signData.origin[] and signData.destination directly to wallet.signTypedData(). No more client-side type reconstruction.
• Server-stored intents. POST /quotes returns an intentId; the full intent stays server-side. Submit via POST /intents with { intentId, signatures } — no more round-tripping intentOp.
• Resource-style endpoints. POST /quotes (was /intents/route), POST /intents (was /intent-operations), GET /intents/:id (was /intent-operation/:id), POST /intents/splits (was /intents/split).
• Flattened cost structure. One cost object per route with input, output, and fees: { total, breakdown }. Replaces scattered tokensSpent / tokensReceived / feeBreakdownUSD / gasCost / sponsorFee.
• Submit response collapsed. POST /intents returns just { intentId } (was { result: { id, status } }). The synthesised status: "FAILED" is gone — simulation failures now surface as 4xx with the unified error envelope.
• Field renames. Notable: destinationGasUnits → destinationGasLimit, sponsorSettings.{gas,bridgeFees,swapFees}Sponsored → {gas,bridgeFees,swapFees}, userAddress → accountAddress. Portfolio token shape uses symbol (was tokenName), chains (was tokenChainBalance), and per-chain address/decimals (were tokenAddress/tokenDecimals). Timestamps move from BigIntLike strings to integer Unix seconds.
• Unified error envelope. All non-2xx responses share { code, message, traceId, details? }. Switch from message-pattern matching to code-based dispatch.
• Schema trimming. Account.mockSignature is gone — use the per-chain Account.mockSignatures map. AccountType.SMART_ACCOUNT is gone — use ERC7579. The accountAccessList flat-array variant is gone — use the structured shape.
• Compact / resource locks removed. No blanc equivalent for topupCompact, emissaryConfig, MultichainCompact origin signatures, or the /withdrawals endpoints.

​

Migrating from alps

// Before (alps) — client round-trips the full intentOp
const { intentOp } = await post("/intents/route", body);
const signatures = await sign(intentOp);
await post("/intent-operations", {
  signedIntentOp: { ...intentOp, ...signatures },
});

// After (blanc) — server stores the intent, client submits signatures by id
const { routes } = await post("/quotes", body);
const { intentId, signData } = routes[0];
const signatures = {
  origin: await Promise.all(signData.origin.map(signTypedData)),
  destination: await signTypedData(signData.destination),
};
await post("/intents", { intentId, signatures });

// Before (alps) — client hashes intent fields with hand-built EIP-712 types
const hash = getIntentHash(intentOp);
const sig = await signer.signTypedData(types, hash);

// After (blanc) — server provides the typed data directly
const sig = await signer.signTypedData(signData.origin[0]);

// Before (alps) — wrapped, with synthesised status
const { result } = await post("/intent-operations", body);
const id = result.id; // result.status was "PENDING" or synthesised "FAILED"

// After (blanc) — id only; simulation failures surface as 4xx
const { intentId } = await post("/intents", body);

// Before (alps)
const op = await get(`/intent-operation/${id}`);
const status = op.result.status;

// After (blanc)
const op = await get(`/intents/${intentId}`);
const status = op.status;

// Before (alps)
{ "chainId": 42161 }
{ "tokenRequirements": { "1": [...], "42161": [...] } }

// After (blanc)
{ "chainId": "eip155:42161" }
{ "tokenRequirements": { "eip155:1": [...], "eip155:42161": [...] } }

GET /accounts/0xabc/portfolio
  ?chainIds=eip155:1&chainIds=eip155:137
  &tokens=eip155:1:0xa0b...&tokens=eip155:137:0xa0b...

// Before (alps)
const gasUSD = response.feeBreakdownUSD.gas;
const inputAmount = response.tokensSpent[0].amount;

// After (blanc)
const gasUSD = route.cost.fees.breakdown.gas.usd;
const inputAmount = route.cost.input[0].amount;

// Before (alps)
{
  sponsorSettings: {
    gasSponsored: true,
    bridgeFeesSponsored: false,
    swapFeesSponsored: false,
  }
}

// After (blanc)
{
  sponsorSettings: {
    gas: true,
    bridgeFees: false,
    swapFees: false,
  }
}

// Before (alps)
{
  account: {
    accountType: "SMART_ACCOUNT",
    mockSignature: "0x...",
  }
}

// After (blanc)
{
  account: {
    accountType: "ERC7579",
    mockSignatures: {
      "eip155:1": "0x...",
      "eip155:42161": "0x...",
    },
  }
}

// Before (alps) — message-pattern matching
if (err.message === "Insufficient balance") { /* ... */ }
if (err.message.startsWith("Unsupported chain ")) { /* ... */ }

// After (blanc) — code-based dispatch
switch (err.code) {
  case "INSUFFICIENT_LIQUIDITY":
    // err.details: { availableIntents, unfillable }
    break;
  case "VALIDATION_ERROR":
    // err.details: [{ message, context? }]
    break;
}

​

Error codes

​

2026-01.alps