Onramp endpoints

onramp.catalog(
  options?: {
    provider?: string       // provider hint, e.g. "banxa"; defaults to the tenant's preferred provider
    country?: string        // explicit ISO-3166-1 alpha-2; wins over clientCountry / GeoIP
    clientCountry?: string  // softer hint → X-Client-Country header
    fiat?: string           // scope payment-method limits/fees + crypto pairs to this fiat
    signal?: AbortSignal
  },
): Promise<OnrampCatalogResponse>

const catalog = await stridge.onramp.catalog({ country: "US" })

console.log(catalog.suggested_fiat)             // "USD" — preselect this
console.log(catalog.fiats.map((f) => f.code))   // ["USD", "EUR", …]
console.log(catalog.country.source)             // "query" — how the country resolved

const { fiats, suggested } = await stridge.onramp.fiats({ country: "US" })
const { crypto } = await stridge.onramp.crypto({ fiat: "USD" })
const { payment_methods } = await stridge.onramp.paymentMethods({ fiat: "USD", crypto: "USDC" })
const { countries } = await stridge.onramp.countries()

onramp.quote(
  payload: {
    fiat_currency: string      // e.g. "USD"
    fiat_amount: string        // positive decimal string, e.g. "100"
    country?: string           // resolved server-side when omitted
    payment_method_id?: string // scope fees/limits to a method
  },
  options?: { clientCountry?: string; signal?: AbortSignal },
): Promise<OnrampQuoteResponse>

const quote = await stridge.onramp.quote({ fiat_currency: "USD", fiat_amount: "100" })

console.log(quote.asset_name, quote.asset_amount) // "USDC", "99.7"
console.log(quote.rate)                            // "1.003" — fiat per 1 unit of crypto
console.log(quote.fees.total)                      // total fee on top of the crypto received

onramp.createSession(
  payload: {
    owner: string                    // your end-user id; owner-scoped keys may only create under their own owner
    fiat_currency: string            // e.g. "USD"
    fiat_amount: string              // positive decimal string
    destination_asset_symbol: string // asset the user receives, e.g. "USDC"
    destination_network_id: string   // network id from catalog crypto[].network_id
    destination_address: string      // the user's wallet; must be allowed for the tenant, else 403
    country?: string
    payment_method_id?: string
    return_app_url?: string          // your page URL; the checkout tab is bounced back here for resume
  },
  options?: {
    clientCountry?: string
    idempotencyKey?: string          // Idempotency-Key header — a retried create returns the same session
    signal?: AbortSignal
  },
): Promise<OnrampSessionResponse>

const session = await stridge.onramp.createSession(
  {
    owner: userId,
    fiat_currency: "USD",
    fiat_amount: "100",
    destination_asset_symbol: "USDC",
    destination_network_id: "60",
    destination_address: walletAddress,
    return_app_url: window.location.href,
  },
  { idempotencyKey: `onramp-${userId}-${Date.now()}` },
)

window.open(session.checkout_url, "_blank") // hand off to the hosted checkout in a new tab

onramp.getSession(
  sessionId: string,
  options?: { ifNoneMatch?: string; signal?: AbortSignal },
): Promise<OnrampSessionResponse>

import { BackendError, isOnrampTerminalState } from "@stridge/sdk"

async function pollUntilTerminal(sessionId: string, etag?: string) {
  for (;;) {
    try {
      const session = await stridge.onramp.getSession(sessionId, { ifNoneMatch: etag })
      etag = session.etag
      if (isOnrampTerminalState(session.state)) return session
    } catch (err) {
      // A matching ETag surfaces as BackendError(304) — nothing changed, keep polling.
      if (!(err instanceof BackendError && err.statusCode === 304)) throw err
    }
    await new Promise((r) => setTimeout(r, 2_000))
  }
}

onramp.listOwnerSessions(
  owner: string,
  options?: {
    state?: string | string[]   // filter by state; an array joins to a comma list
    provider?: string
    destinationAsset?: string    // → destination_asset_symbol query
    destinationNetwork?: string  // → destination_network_id query
    fiat?: string
    country?: string
    q?: string                   // free-text search
    from?: string                // created-at lower bound (RFC3339)
    to?: string                  // created-at upper bound (RFC3339)
    sort?: string
    order?: "asc" | "desc"
    limit?: number
    offset?: number
    includeTotals?: boolean      // include aggregate totals in the response
    signal?: AbortSignal
  },
): Promise<OnrampSessionListResponse>

const { sessions, page_info } = await stridge.onramp.listOwnerSessions(userId, {
  state: ["SESSION_COMPLETED", "SESSION_FAILED"],
  limit: 20,
})

interface OnrampSessionResponse {
  session_id: string
  state: OnrampSessionState         // create always returns "SESSION_PENDING"
  checkout_url?: string             // provider-hosted page; present on create
  provider_order_id?: string
  external_order_id: string
  flow: {
    fiat: { currency: string; amount: string }                       // what the user pays
    entry: {                                                          // crypto the provider deposits, + the address
      address: string
      network_id: string
      asset: string
      amount: string
      tx_hash?: string                                               // the UDA deposit tx (settlement correlation)
      settlement_state?: "pending" | "succeeded" | "failed"          // the delivery-leg outcome
    }
    destination: {                                                    // what the user receives, and where
      address: string
      network_id: string
      asset: string
      amount: string
      tx_hash?: string                                               // receipt, populated alongside settlement_state: "succeeded"
    }
  }
  expires_at?: string
  etag: string                      // pass back as If-None-Match for cheap polling
}

import { OnrampSessionState, ONRAMP_TERMINAL_STATES, isOnrampTerminalState } from "@stridge/sdk"

onramp.setSessionState(
  sessionId: string,
  payload: { state: OnrampSessionState; failure_code?: string },
  options?: { signal?: AbortSignal },
): Promise<OnrampSessionResponse>

// Drive a pending session to the provider-completed state…
await stridge.onramp.setSessionState(session.session_id, { state: "SESSION_COMPLETED" })

// …or to a specific failure:
await stridge.onramp.setSessionState(session.session_id, {
  state: "SESSION_FAILED",
  failure_code: "payment_declined",
})

const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), 10_000)

try {
  const session = await stridge.onramp.getSession(sessionId, { signal: controller.signal })
  // …
} finally {
  clearTimeout(timer)
}