Examples

const BASE = 'https://sandbox-api.matinee.ai/v1'

type Options = { idempotencyKey?: string; body?: unknown; method?: string }

export async function call<T>(path: string, options: Options = {}): Promise<T> {
  const response = await fetch(BASE + path, {
    method: options.method ?? (options.body ? 'POST' : 'GET'),
    headers: {
      // An API key is scoped to one environment and one organization.
      Authorization: `Bearer ${process.env.MATINEE_API_KEY}`,
      'X-Organization-ID': process.env.MATINEE_ORG_ID!,
      'X-Environment': 'sandbox',
      // Echoed back on every response and every error. Log it — it is what
      // support will ask for.
      'X-Request-ID': crypto.randomUUID(),
      'Content-Type': 'application/json',
      // Required on writes that declare idempotency. Reusing a key with a
      // different body is rejected as idempotency_key_reused rather than
      // quietly applying the second one.
      ...(options.idempotencyKey ? { 'Idempotency-Key': options.idempotencyKey } : {}),
    },
    body: options.body ? JSON.stringify(options.body) : undefined,
  })

  // Every response carries the same envelope: { data, meta }.
  const payload = await response.json()
  if (!response.ok) throw new ApiError(payload.error, payload.meta.request_id)
  return payload.data as T
}

Headers are §4 of the API specification. The response envelope is §5 — success and failure both carry meta.request_id.

// Earned at the end of a match, from the event the game server already emits.
await call('/events', {
  idempotencyKey: match.id,
  body: {
    type: 'match.completed',
    external_event_id: match.id,
    customer_id: player.customerId,
    data: { placement: match.placement, duration_s: match.durationSeconds },
  },
})

// Spent in the store. Direct issuance for a one-off grant that no rule covers —
// a compensation grant, a launch bonus — rather than routing it through an event.
await call(`/assets/${currency.id}/issue`, {
  idempotencyKey: `compensation-${incident.id}-${player.customerId}`,
  body: { wallet_id: player.walletId, amount: '500', reason: 'Server downtime compensation' },
})

// Redeeming for an in-game item. Fails closed: insufficient_balance if the
// player cannot afford it, asset_paused if the economy is frozen.
await call(`/assets/${currency.id}/redemptions`, {
  idempotencyKey: `purchase-${cart.id}`,
  body: { wallet_id: player.walletId, amount: item.price, reference: item.sku },
})

// Player-to-player trade, if the economy allows it. Wallet policies are checked
// here, not in your code.
await call(`/assets/${currency.id}/transfers`, {
  idempotencyKey: `trade-${trade.id}`,
  body: { from_wallet_id: seller.walletId, to_wallet_id: buyer.walletId, amount: trade.amount },
})

Nothing here touches a blockchain. An asset lives on internal infrastructure until it is explicitly deployed, and deployment is a separate, confirmed action.

// The signing secret is returned once, when the endpoint is created, and
// never again. Store it before you discard the response.
const endpoint = await call('/webhooks', {
  idempotencyKey: 'webhook-rewards',
  body: {
    url: 'https://example.com/hooks/matinee',
    events: ['reward.issued', 'asset.paused', 'wallet.frozen'],
  },
})

// Verify before you trust. Compare in constant time — a plain === leaks the
// signature a byte at a time to anyone willing to measure.
import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(rawBody: string, signature: string, secret: string) {
  const expected = createHmac('sha256', secret).update(rawBody).digest()
  const received = Buffer.from(signature, 'hex')
  return expected.length === received.length && timingSafeEqual(expected, received)
}

// Handlers must be idempotent. A webhook can arrive more than once, and the
// same delivery can overlap with your own poll of the same resource.

An event that failed to process can be reprocessed with POST /events/{id}/replay rather than re-sent from your side, which would collide with deduplication.