tapimo 0.2.0 → 0.3.0

package/src/internal/Fees.ts

@@ -0,0 +1,51 @@
+import { Hex } from 'ox'
+
+// Tempo gas prices (`maxFeePerGas`, `effectiveGasPrice`, block base fee) are
+// denominated in attodollars (10^-18 USD) per gas, while fee-token balances
+// use 6 decimals (microdollars, 10^-6 USD). The charged fee is
+// `ceil(gas × gasPrice / 10^12)`, mirroring `calc_gas_balance_spending` in
+// tempoxyz/tempo.
+
+/** Attodollar exponent gas prices use (10^-18 USD per gas), fixed by the fee spec. */
+const attoDecimals = 18
+
+/** Fee-token decimals: TIP-20 fixes 6 (1 token unit = 1 microdollar). */
+export const tokenDecimals = 6
+
+/** Scaling between attodollar gas math and fee-token units, derived from the exponents. */
+export const scalingFactor = 10n ** BigInt(attoDecimals - tokenDecimals)
+
+/**
+ * Fee in fee-token base units for a gas amount priced in attodollars per gas
+ * (ceiling division). Works for actual fees (`gasUsed × effectiveGasPrice`)
+ * and signed caps (`gas × maxFeePerGas`) alike.
+ *
+ * @param gas - Gas amount.
+ * @param gasPrice - Price in attodollars per gas.
+ * @returns The fee in fee-token base units.
+ */
+export function fromGas(gas: bigint, gasPrice: bigint): bigint {
+  return (gas * gasPrice + scalingFactor - 1n) / scalingFactor
+}
+
+/**
+ * Signed fee cap of a candidate transaction in fee-token base units:
+ * `gas × maxFeePerGas` (attodollars) scaled through {@link fromGas}. Undefined
+ * when either field is missing or unparseable, so callers can fail closed.
+ *
+ * @param request - Transaction-shaped fee fields.
+ * @returns The cap in base units, or undefined.
+ */
+export function maxOf(request: { gas?: unknown; maxFeePerGas?: unknown }): bigint | undefined {
+  const gas = toBigInt(request.gas)
+  const maxFeePerGas = toBigInt(request.maxFeePerGas)
+  if (gas === undefined || maxFeePerGas === undefined) return undefined
+  return fromGas(gas, maxFeePerGas)
+}
+
+/** Fee fields arrive as bigints (raw envelopes) or hex quantities (fills). */
+function toBigInt(value: unknown): bigint | undefined {
+  if (typeof value === 'bigint') return value
+  if (typeof value === 'string' && Hex.validate(value)) return Hex.toBigInt(value)
+  return undefined
+}

package/src/internal/FundingRoutes.ts

@@ -0,0 +1,583 @@
+/** Tempo mainnet as a CAIP-2 chain reference. */
+const destinationChain = {
+  addressFormat: 'evm',
+  id: 'eip155:4217',
+  kind: 'evm',
+  name: 'Tempo',
+} as const
+
+/** Tempo token used when the caller omits `destinationToken`. */
+const defaultDestinationToken = 'usdce'
+
+/** Source chains accepted by the funding route inventory. */
+const sourceChains = [
+  {
+    addressFormat: 'evm',
+    aliases: ['ethereum', 'eth', 'eip155:1'],
+    id: 'eip155:1',
+    kind: 'evm',
+    name: 'Ethereum',
+    providerIds: {
+      across: '1',
+      bridge: 'ethereum',
+      bungee: '1',
+      lifi: '1',
+      relay: '1',
+    },
+    slug: 'ethereum',
+    tokens: [
+      {
+        address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+        coingeckoId: 'usd-coin',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'ERC-20',
+        symbol: 'USDC',
+      },
+      {
+        address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'ERC-20',
+        symbol: 'USDT',
+      },
+      {
+        address: '0x6c3ea9036406852006290770bedfcaba0e23a0e8',
+        coingeckoId: 'paypal-usd',
+        decimals: 6,
+        name: 'PayPal USD',
+        standard: 'ERC-20',
+        symbol: 'PYUSD',
+      },
+      {
+        address: '0x1abaea1f7c830bd89acc67ec4af516284b1bc33c',
+        coingeckoId: 'euro-coin',
+        decimals: 6,
+        name: 'Euro Coin',
+        standard: 'ERC-20',
+        symbol: 'EURC',
+      },
+      {
+        address: '0x6b175474e89094c44da98b954eedeac495271d0f',
+        coingeckoId: 'dai',
+        decimals: 18,
+        name: 'Dai Stablecoin',
+        standard: 'ERC-20',
+        symbol: 'DAI',
+      },
+    ],
+  },
+  {
+    addressFormat: 'evm',
+    aliases: ['base', 'eip155:8453'],
+    id: 'eip155:8453',
+    kind: 'evm',
+    name: 'Base',
+    providerIds: {
+      across: '8453',
+      bridge: 'base',
+      bungee: '8453',
+      lifi: '8453',
+      relay: '8453',
+    },
+    slug: 'base',
+    tokens: [
+      {
+        address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+        coingeckoId: 'usd-coin',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'ERC-20',
+        symbol: 'USDC',
+      },
+      {
+        address: '0xfde4c96c8593536e31f229ea8f37b2ada2699bb2',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'ERC-20',
+        symbol: 'USDT',
+      },
+      {
+        address: '0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42',
+        coingeckoId: 'euro-coin',
+        decimals: 6,
+        name: 'Euro Coin',
+        standard: 'ERC-20',
+        symbol: 'EURC',
+      },
+    ],
+  },
+  {
+    addressFormat: 'evm',
+    aliases: ['bnb', 'bsc', 'eip155:56'],
+    id: 'eip155:56',
+    kind: 'evm',
+    name: 'BNB Smart Chain',
+    providerIds: {
+      across: '56',
+      bungee: '56',
+      lifi: '56',
+      relay: '56',
+    },
+    slug: 'bnb',
+    tokens: [
+      {
+        address: '0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d',
+        coingeckoId: 'usd-coin',
+        decimals: 18,
+        name: 'Binance-Peg USD Coin',
+        standard: 'BEP-20',
+        symbol: 'USDC',
+      },
+      {
+        address: '0x55d398326f99059ff775485246999027b3197955',
+        coingeckoId: 'tether',
+        decimals: 18,
+        name: 'Tether USD',
+        standard: 'BEP-20',
+        symbol: 'USDT',
+      },
+    ],
+  },
+  {
+    addressFormat: 'solana',
+    aliases: ['solana', 'solana:mainnet'],
+    id: 'solana:mainnet',
+    kind: 'solana',
+    name: 'Solana',
+    providerIds: {
+      bridge: 'solana',
+      relay: 'solana',
+    },
+    slug: 'solana',
+    tokens: [
+      {
+        address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        coingeckoId: 'usd-coin',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'SPL',
+        symbol: 'USDC',
+      },
+      {
+        address: 'Es9vMFrzaCERmJfrF4H2FYD4KCo3LwC1uix9YEaQ8t1v',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'SPL',
+        symbol: 'USDT',
+      },
+    ],
+  },
+  {
+    addressFormat: 'tron',
+    aliases: ['tron', 'tron:mainnet'],
+    id: 'tron:mainnet',
+    kind: 'tron',
+    name: 'Tron',
+    providerIds: {
+      bridge: 'tron',
+      relay: 'tron',
+    },
+    slug: 'tron',
+    tokens: [
+      {
+        address: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'TRC-20',
+        symbol: 'USDT',
+      },
+    ],
+  },
+] as const
+
+/** Tempo destination tokens supported by the initial funding route inventory. */
+const destinationTokens = [
+  {
+    address: '0x20c0000000000000000000000000000000000000',
+    decimals: 6,
+    name: 'pathUSD',
+    slug: 'pathusd',
+    standard: 'TIP-20',
+    symbol: 'pathUSD',
+  },
+  {
+    address: '0x20c000000000000000000000b9537d11c60e8b50',
+    decimals: 6,
+    name: 'Bridged USDC (Stargate)',
+    slug: 'usdce',
+    standard: 'TIP-20',
+    symbol: 'USDC.e',
+  },
+  {
+    address: '0x20c0000000000000000000001621e21f71cf12fb',
+    decimals: 6,
+    name: 'Bridged EURC',
+    slug: 'eurce',
+    standard: 'TIP-20',
+    symbol: 'EURC.e',
+  },
+  {
+    address: '0x20c00000000000000000000014f22ca97301eb73',
+    decimals: 6,
+    name: 'USDT0',
+    slug: 'usdt0',
+    standard: 'TIP-20',
+    symbol: 'USDT0',
+  },
+  {
+    address: '0x20c0000000000000000000003554d28269e0f3c2',
+    decimals: 6,
+    name: 'frxUSD',
+    slug: 'frxusd',
+    standard: 'TIP-20',
+    symbol: 'frxUSD',
+  },
+] as const
+
+/** Providers exposed by the generic provider catalog. */
+const providers = [
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'across',
+    kind: 'intentBridge',
+    name: 'Across',
+    requiresApiKey: true,
+    status: 'inventoryOnly',
+  },
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'relay',
+    kind: 'solverNetwork',
+    name: 'Relay',
+    requiresApiKey: false,
+    status: 'inventoryOnly',
+  },
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'bridge',
+    kind: 'enterpriseTransfer',
+    name: 'Bridge.xyz',
+    requiresApiKey: true,
+    status: 'inventoryOnly',
+  },
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'bungee',
+    kind: 'aggregator',
+    name: 'Bungee',
+    requiresApiKey: false,
+    status: 'inventoryOnly',
+  },
+  {
+    capabilities: ['fundingRoutes'],
+    id: 'lifi',
+    kind: 'aggregator',
+    name: 'LI.FI',
+    requiresApiKey: true,
+    status: 'planned',
+  },
+] as const
+
+type TokenInput = (typeof sourceChains)[number]['tokens'][number]
+type DestinationTokenInput = (typeof destinationTokens)[number]
+type ProviderInput = (typeof providers)[number]
+type SourceChainInput = (typeof sourceChains)[number]
+
+/** Static provider support rows used until live quote adapters are configured. */
+const inventory: readonly InventoryEntry[] = [
+  { destinationToken: 'usdce', provider: 'across', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'relay', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC', 'USDT'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'bridge', sourceChains: ['ethereum', 'base', 'solana'], sourceTokens: ['USDC'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'bridge', sourceChains: ['ethereum', 'solana', 'tron'], sourceTokens: ['USDT'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'bungee', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
+]
+
+type InventoryEntry = {
+  destinationToken: string
+  provider: ProviderInput['id']
+  sourceChains: readonly string[]
+  sourceTokens: readonly string[]
+}
+
+/** Lists normalized chains and source tokens that can fund Tempo. */
+export function listChains() {
+  return sourceChains.map((chain) => ({
+    ...formatChain(chain),
+    tokens: chain.tokens.map((token) => formatSourceToken(chain, token)),
+  }))
+}
+
+/** Lists providers, optionally filtered by one provider capability. */
+export function listProviders(options: listProviders.Options = {}) {
+  return providers
+    .filter((provider) =>
+      options.capability === undefined ? true : provider.capabilities.includes(options.capability),
+    )
+    .map(formatProvider)
+}
+
+export declare namespace listProviders {
+  /** Options for listing providers. */
+  type Options = {
+    /** Provider capability to require. */
+    capability?: Capability | undefined
+  }
+}
+
+/** Lists static funding route candidates for a normalized caller request. */
+export function listRoutes(options: listRoutes.Options) {
+  const sourceChain = resolveSourceChain(options.sourceChain)
+  const sourceToken = resolveSourceToken(sourceChain, options.sourceToken)
+  const destinationToken = resolveDestinationToken(options.destinationToken)
+  const provider = options.provider ? resolveProvider(options.provider) : undefined
+
+  if (!sourceToken) {
+    validateSourceAmountSyntax(options.sourceAmount, options.sourceAmountUnits)
+    return []
+  }
+
+  const sourceAmount = resolveSourceAmount({
+    amount: options.sourceAmount,
+    token: sourceToken,
+    units: options.sourceAmountUnits,
+  })
+
+  return inventory
+    .filter((entry) => entry.sourceChains.includes(sourceChain.slug))
+    .filter((entry) => entry.sourceTokens.includes(sourceToken.symbol))
+    .filter((entry) => entry.destinationToken === destinationToken.slug)
+    .filter((entry) => provider === undefined || entry.provider === provider.id)
+    .slice(0, options.limit)
+    .map((entry) => {
+      const entryProvider = providers.find((candidate) => candidate.id === entry.provider)!
+      return {
+        destinationChain,
+        destinationToken: formatDestinationToken(destinationToken),
+        id: [
+          sourceChain.slug,
+          sourceToken.symbol.toLowerCase(),
+          'tempo',
+          destinationToken.slug,
+          entryProvider.id,
+        ].join('-'),
+        provider: formatProviderRef(entryProvider),
+        quality: {
+          availableVolumeUsd: null,
+          estimatedSeconds: null,
+          feeBps: null,
+          historicalVolumeUsd24h: null,
+          instantVolumeUsd: null,
+          liquiditySource: 'staticInventory',
+          score: null,
+          tier: 'unknown' as const,
+        },
+        sourceAmount,
+        sourceChain: formatChain(sourceChain),
+        sourceToken: formatSourceToken(sourceChain, sourceToken),
+        status: 'unknown' as const,
+      }
+    })
+}
+
+export declare namespace listRoutes {
+  /** Options for listing funding routes. */
+  type Options = {
+    /** Optional Tempo destination token symbol, address, or token key. */
+    destinationToken?: string | undefined
+    /** Maximum number of route candidates to return. */
+    limit: number
+    /** Optional provider id filter. */
+    provider?: string | undefined
+    /** Source amount as supplied by the caller. */
+    sourceAmount: string
+    /** Unit used by {@link sourceAmount}. */
+    sourceAmountUnits: SourceAmountUnits
+    /** Chain alias or CAIP-2 source chain id. */
+    sourceChain: string
+    /** Source token symbol, contract address, mint, or Tempo token key. */
+    sourceToken: string
+  }
+}
+
+/** Provider capability identifiers accepted by the generic provider catalog. */
+export type Capability = 'fundingRoutes'
+
+/** Source amount unit accepted by the funding route request. */
+export type SourceAmountUnits = 'baseUnits' | 'decimal'
+
+function tokenKey(chain: { id: string }, token: TokenInput | DestinationTokenInput) {
+  const standard =
+    token.standard === 'SPL' ? 'spl' : token.standard === 'TRC-20' ? 'trc20' : 'erc20'
+  return `${chain.id}/${standard}:${token.address}`
+}
+
+function decimalFromBaseUnits(baseUnits: string, decimals: number) {
+  const padded = baseUnits.padStart(decimals + 1, '0')
+  const whole = decimals === 0 ? padded : padded.slice(0, -decimals)
+  const fraction = decimals === 0 ? '' : padded.slice(-decimals).replace(/0+$/, '')
+  return fraction ? `${whole}.${fraction}` : whole
+}
+
+function formatChain(chain: SourceChainInput) {
+  const { addressFormat, id, kind, name, providerIds } = chain
+  return { addressFormat, id, kind, name, providerIds }
+}
+
+function formatDestinationToken(token: DestinationTokenInput) {
+  return {
+    address: token.address,
+    decimals: token.decimals,
+    metadata: {},
+    name: token.name,
+    standard: token.standard,
+    symbol: token.symbol,
+    tokenKey: tokenKey(destinationChain, token),
+    verified: true,
+  }
+}
+
+function formatProvider(provider: ProviderInput) {
+  const { id, kind, name, requiresApiKey, status } = provider
+  return { capabilities: [...provider.capabilities], id, kind, name, requiresApiKey, status }
+}
+
+function formatProviderRef(provider: ProviderInput) {
+  const { id, kind, name, requiresApiKey } = provider
+  return { id, kind, name, requiresApiKey }
+}
+
+function formatSourceToken(chain: SourceChainInput, token: TokenInput) {
+  return {
+    address: token.address,
+    decimals: token.decimals,
+    metadata: { coingeckoId: token.coingeckoId },
+    name: token.name,
+    standard: token.standard,
+    symbol: token.symbol,
+    tokenKey: tokenKey(chain, token),
+    verified: true,
+  }
+}
+
+function normalizeInput(value: string) {
+  return value.trim().toLowerCase()
+}
+
+function parseBaseUnits(value: string) {
+  if (!/^\d+$/.test(value) || BigInt(value) <= 0n) throw new InvalidAmountError()
+  return BigInt(value).toString()
+}
+
+function parseDecimalUnits(value: string, decimals: number) {
+  if (!/^\d+(\.\d+)?$/.test(value)) throw new InvalidAmountError()
+  const [whole, fraction = ''] = value.split('.')
+  if (fraction.length > decimals) throw new InvalidAmountError()
+  const baseUnits = BigInt(`${whole}${fraction.padEnd(decimals, '0')}`)
+  if (baseUnits <= 0n) throw new InvalidAmountError()
+  return baseUnits.toString()
+}
+
+function resolveDestinationToken(input: string | undefined) {
+  if (input === undefined) return destinationTokens.find((token) => token.slug === defaultDestinationToken)! // prettier-ignore
+  const normalized = normalizeInput(input)
+  const token = destinationTokens.find(
+    (candidate) =>
+      candidate.slug === normalized ||
+      candidate.symbol.toLowerCase() === normalized ||
+      candidate.address === normalized ||
+      tokenKey(destinationChain, candidate).toLowerCase() === normalized,
+  )
+  if (!token) throw new UnsupportedDestinationTokenError()
+  return token
+}
+
+function resolveProvider(input: string) {
+  const provider = providers.find((candidate) => candidate.id === normalizeInput(input))
+  if (!provider) throw new UnsupportedProviderError()
+  return provider
+}
+
+function resolveSourceAmount(options: resolveSourceAmount.Options) {
+  const amount =
+    options.units === 'baseUnits'
+      ? parseBaseUnits(options.amount)
+      : parseDecimalUnits(options.amount, options.token.decimals)
+  return {
+    amount,
+    formatted: decimalFromBaseUnits(amount, options.token.decimals),
+    usd: null,
+  }
+}
+
+declare namespace resolveSourceAmount {
+  type Options = {
+    amount: string
+    token: TokenInput
+    units: SourceAmountUnits
+  }
+}
+
+function resolveSourceToken(chain: SourceChainInput, input: string) {
+  const trimmed = input.trim()
+  const normalized = trimmed.toLowerCase()
+  return chain.tokens.find(
+    (token) =>
+      token.symbol.toLowerCase() === normalized ||
+      matchesTokenIdentifier(chain, token.address, trimmed, normalized) ||
+      matchesTokenIdentifier(chain, tokenKey(chain, token), trimmed, normalized),
+  )
+}
+
+function matchesTokenIdentifier(
+  chain: SourceChainInput,
+  candidate: string,
+  trimmed: string,
+  normalized: string,
+) {
+  return chain.kind === 'evm' ? candidate.toLowerCase() === normalized : candidate === trimmed
+}
+
+function resolveSourceChain(input: string) {
+  const normalized = normalizeInput(input)
+  const chain = sourceChains.find(
+    (candidate) =>
+      candidate.id === normalized || (candidate.aliases as readonly string[]).includes(normalized),
+  )
+  if (!chain) throw new UnsupportedSourceChainError()
+  return chain
+}
+
+function validateSourceAmountSyntax(value: string, units: SourceAmountUnits) {
+  if (units === 'baseUnits') {
+    parseBaseUnits(value)
+    return
+  }
+  if (!/^\d+(\.\d+)?$/.test(value)) throw new InvalidAmountError()
+  const [whole, fraction = ''] = value.split('.')
+  if (BigInt(`${whole}${fraction}`) <= 0n) throw new InvalidAmountError()
+}
+
+/** Error thrown when the caller supplies an unsupported destination token. */
+export class UnsupportedDestinationTokenError extends Error {
+  override name = 'FundingRoutes.UnsupportedDestinationTokenError'
+}
+
+/** Error thrown when the caller supplies an invalid source amount. */
+export class InvalidAmountError extends Error {
+  override name = 'FundingRoutes.InvalidAmountError'
+}
+
+/** Error thrown when the caller filters to an unknown provider. */
+export class UnsupportedProviderError extends Error {
+  override name = 'FundingRoutes.UnsupportedProviderError'
+}
+
+/** Error thrown when the caller supplies an unsupported source chain. */
+export class UnsupportedSourceChainError extends Error {
+  override name = 'FundingRoutes.UnsupportedSourceChainError'
+}

package/src/internal/Id.test.ts

@@ -0,0 +1,17 @@
+import * as Id from './Id.js'
+
+describe('generate', () => {
+  test('produces a prefixed 24-char base62 id', () => {
+    expect(Id.generate('usr')).toMatch(/^usr_[0-9A-Za-z]{24}$/)
+  })
+
+  test('never emits `_` or `-` in the random segment', () => {
+    for (let i = 0; i < 100; i++) expect(Id.generate('org').slice(4)).toMatch(/^[0-9A-Za-z]{24}$/)
+  })
+})
+
+describe('random', () => {
+  test('produces a 24-char base62 segment', () => {
+    expect(Id.random()).toMatch(/^[0-9A-Za-z]{24}$/)
+  })
+})

package/src/internal/Id.ts

@@ -0,0 +1,24 @@
+import { customAlphabet } from 'nanoid'
+
+/** Base62 alphabet: `_` and `-` excluded so the prefix separator stays unambiguous. */
+const segment = customAlphabet('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz', 24)
+
+/**
+ * Generates a prefixed resource id (`{prefix}_{24 base62 chars}`, ~143 bits).
+ *
+ * @param prefix - The resource-type prefix (e.g. `usr`, `org`).
+ * @returns The generated id.
+ */
+export function generate(prefix: string): string {
+  return `${prefix}_${random()}`
+}
+
+/**
+ * Generates the random segment of an id (24 base62 chars) without a prefix,
+ * for ids composing extra parts (e.g. `wh_{timestamp}_{random}`).
+ *
+ * @returns The generated segment.
+ */
+export function random(): string {
+  return segment()
+}

package/src/internal/Log.test.ts

@@ -74,6 +74,7 @@ describe('middleware', () => {
         "method": "GET",
         "path": "/secure",
         "principal": {
+          "billingActive": false,
           "environment": "production",
           "id": "key_1",
           "orgId": "org_1",

package/src/internal/Log.ts

@@ -47,6 +47,8 @@ export type Entry = {
     | {
         /** Attributed super admin identity for super admin callers. */
         actor?: string | undefined
+        /** Whether the owning org's billing was active for API-key callers; drives request-metered billing. */
+        billingActive?: boolean | undefined
         /** Key environment for API-key callers. */
         environment?: ApiKey.ApiKey['environment'] | undefined
         /** Principal id: the API key id, the public quota identity, the user id, or `super_admin`. */
@@ -151,6 +153,9 @@ export function middleware<environment extends Environment = Environment>(
         : {
             principal: {
               ...(principal.type === 'super_admin' ? { actor: principal.actor } : {}),
+              ...(principal.type === 'api_key'
+                ? { billingActive: principal.apiKey.billingActive === true }
+                : {}),
               ...(principal.type === 'api_key' ? { environment: principal.environment } : {}),
               id: principal.id,
               ...(principal.type === 'api_key' ? { orgId: principal.orgId } : {}),