> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Typed Macropay client for Node.js and the browser — checkout, billing, and agent metering in a few lines.

The `@macropayments/sdk` package is the fastest way to talk to Macropay from any
JavaScript runtime. It ships full TypeScript types, async pagination helpers, and
covers the entire v1 API — from hosted checkout to usage meters to agent
[Signals](/integrate/sdk/adapters/express). Because Macropay is your **merchant of
record**, the same calls that move money also handle sales tax, VAT, and PCI scope
on your behalf.

## Install

<Tabs>
  <Tab title="npm">
    ```bash Terminal theme={null}
    npm install @macropayments/sdk
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash Terminal theme={null}
    pnpm add @macropayments/sdk
    ```
  </Tab>

  <Tab title="yarn">
    ```bash Terminal theme={null}
    yarn add @macropayments/sdk
    ```
  </Tab>
</Tabs>

## Configure the client

Create one `Macropay` instance and reuse it. Point it at `sandbox` while you
build, then flip the env var to `production` when you go live — no code changes.

```typescript icon="square-js" macropay.ts theme={null}
import { Macropay } from '@macropayments/sdk'

export const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN,
  server: process.env.MACROPAY_MODE || 'sandbox', // 'sandbox' | 'production'
})
```

<Tip>
  Generate an **Organization Access Token (OAT)** in the
  [dashboard](https://app.macropay.ai) and store it as `MACROPAY_ACCESS_TOKEN`.
  Never ship a token to the browser — keep checkout and billing calls server-side.
</Tip>

## Your first call

List operations return an async iterator, so paging through results is a single
`for await` loop. Here we walk every benefit a customer has unlocked — license
keys, downloads, Discord access, and so on.

```typescript icon="square-js" list-benefits.ts theme={null}
import { macropay } from './macropay'

async function run() {
  const result = await macropay.users.benefits.list({})

  for await (const page of result) {
    console.log(page) // each page of granted benefits
  }
}

run()
```

### Spin up a checkout

Everything you sell — one-time or subscription — is a **product**, so the call
shape is identical. Create a checkout session and redirect the customer to the
hosted, fully localized payment page:

```typescript icon="square-js" checkout.ts theme={null}
import { macropay } from './macropay'

const checkout = await macropay.checkouts.create({
  products: ['prod_starter_plan'],
  successUrl: 'https://example.com/thanks',
})

// Send the buyer here — card data is tokenized in our PCI DSS Level 1 vault.
return Response.redirect(checkout.url)
```

Tax is calculated, collected, and remitted by Macropay as the seller of record,
so the merchant of record on the buyer's statement is us — not you.

## Meter AI and agent usage

Bill for what your product actually does — tokens consumed, actions taken, or
outcomes delivered — by ingesting events. Meters aggregate those events into a
metered price, and you can certify agent ROI with value receipts.

```typescript icon="square-js" ingest-usage.ts theme={null}
import { macropay } from './macropay'

// Report metered usage (e.g. tokens an agent burned this run)
await macropay.events.ingest({
  events: [
    {
      name: 'ai_tokens',
      externalCustomerId: 'cus_acme',
      metadata: { tokens: 12_480, model: 'gpt-4o-mini' },
    },
  ],
})
```

<Info>
  Routing model calls through the OpenAI-compatible **AI proxy** at `/ai/v1`
  captures token cost automatically — no manual event ingestion needed. See the
  proxy and agent-billing flows in the [adapter guides](/integrate/sdk/adapters/hono).
</Info>

## camelCase in TypeScript

The Macropay API and reference docs use `snake_case`, but this SDK exposes
`camelCase` to match JS/TS convention. Modern editors surface the camelCase
fields via the bundled types, so the mapping is usually invisible — just keep it
in mind when copying field names straight from the [API
reference](/integrate/sdk/adapters/nextjs).

| In the docs (API)      | In the SDK           |
| ---------------------- | -------------------- |
| `success_url`          | `successUrl`         |
| `external_customer_id` | `externalCustomerId` |
| `metered_price`        | `meteredPrice`       |

<Note>
  A future release will let you opt into `snake_case` in TypeScript so SDK code maps
  one-to-one with the API design and documentation.
</Note>

## Framework adapters

Wire up hosted checkout and signature-verified webhook handlers in a handful of
lines — pick the adapter for your stack:

<CardGroup cols={2}>
  <Card title="Next.js" href="/integrate/sdk/adapters/nextjs" />

  <Card title="Express" href="/integrate/sdk/adapters/express" />

  <Card title="Hono" href="/integrate/sdk/adapters/hono" />

  <Card title="Fastify" href="/integrate/sdk/adapters/fastify" />

  <Card title="Remix" href="/integrate/sdk/adapters/remix" />

  <Card title="SvelteKit" href="/integrate/sdk/adapters/sveltekit" />

  <Card title="Nuxt" href="/integrate/sdk/adapters/nuxt" />

  <Card title="Astro" href="/integrate/sdk/adapters/astro" />

  <Card title="Elysia" href="/integrate/sdk/adapters/elysia" />

  <Card title="TanStack Start" href="/integrate/sdk/adapters/tanstack-start" />

  <Card title="Deno" href="/integrate/sdk/adapters/deno" />

  <Card title="Better Auth" href="/integrate/sdk/adapters/better-auth" />
</CardGroup>