Examples

Usage-based pricing

Charge for what they call: your markup on the wire, their wallet on the meter.

Acme Search sells retrieval as pay-as-you-go. No monthly allotment. End users top up dollars (or start with a small trial grant). Every call draws the money wallet at Acme’s sell price. A key cap stops a runaway agent from emptying the account in one night.

Piece	Choice
Aliases	`acme/fast`, `acme/smart`
Router (optional)	`balanced` over those two
Bundle	`paygo`, no subscription price
Margin	25% markup, or fixed sell prices on hot models
Balance	Money wallet; trial grant then top-ups
Safety	$10 key cap per credential

Aliases, bundle, and markup

Create the names first, allow them on the bundle, then set markup (or sell prices). An optional router is attached automatically once its targets are on the bundle.

Create the aliases

seams models add acme/fast --source anthropic/claude-haiku-4.5
seams models add acme/smart --source anthropic/claude-sonnet-4

await seams.models.add("acme/fast", {
  sources: [{ provider: "anthropic", model: "claude-haiku-4.5" }],
})
await seams.models.add("acme/smart", {
  sources: [{ provider: "anthropic", model: "claude-sonnet-4" }],
})

from seams import models

seams.models.add(
    "acme/fast",
    sources=[models.AddModelSource(provider="anthropic", model="claude-haiku-4.5")],
)
seams.models.add(
    "acme/smart",
    sources=[models.AddModelSource(provider="anthropic", model="claude-sonnet-4")],
)

Create the bundle and allow those names

seams bundles add paygo --name "Pay as you go" --markup 25%
seams bundles allow paygo acme/fast acme/smart

# optional: pin sell prices instead of markup on a model
seams bundles price paygo acme/smart --input 3 --output 15

await seams.bundles.create("paygo", {
  displayName: "Pay as you go",
  markupBps: 2500, // 25%
})
await seams.bundles.allow("paygo", { models: ["acme/fast", "acme/smart"] })
await seams.bundles.price("paygo", {
  model: "acme/smart",
  sell: { input: "3000000", output: "15000000" }, // $/MTok as micros
})

seams.bundles.create("paygo", display_name="Pay as you go", markup_bps=2500)
seams.bundles.allow("paygo", models=["acme/fast", "acme/smart"])
seams.bundles.price(
    "paygo",
    model="acme/smart",
    sell={"input": "3000000", "output": "15000000"},
)

Optional: a router over those aliases

Create the router after the targets are allowed on at least one bundle. Seams attaches it to every bundle that already allows all of its targets. Callers use the router slug the same way they use an alias.

seams routers add balanced --strategy round_robin \
  --target acme/fast --target acme/smart
# callers may use model: "balanced" or "acme/smart"

await seams.routers.add("balanced", {
  strategy: "round_robin",
  targets: [{ model: "acme/fast" }, { model: "acme/smart" }],
})
// callers may use model: "balanced" or "acme/smart"

seams.routers.add(
    "balanced",
    strategy="round_robin",
    targets=[
        models.AddRouterTarget(model="acme/fast"),
        models.AddRouterTarget(model="acme/smart"),
    ],
)

await seams.users.create(user.id, { email: user.email, bundle: "paygo" })
const key = await seams.keys.mint({
  endUserId: user.id,
  bundle: "paygo",
  name: user.email,
  capMicros: "10000000", // $10.00
})

// trial: $2.00 on the money wallet (always micros)
await seams.grants.issue({
  endUsers: [user.id],
  amountUnits: "2000000",
  reason: "trial",
  idempotencyKey: `trial:${user.id}`,
})

seams.users.create(user.id, email=user.email, bundle="paygo")
key = seams.keys.mint(
    end_user_id=user.id,
    bundle="paygo",
    name=user.email,
    cap_micros="10000000",
)
seams.grants.issue(
    end_users=[user.id],
    amount_units="2000000",
    reason="trial",
    idempotency_key=f"trial:{user.id}",
)

Top-up after checkout

Usage-based still needs a funded wallet unless you settle elsewhere and grant after the fact. On payment success, credit micros with the payment id as the idempotency key.

typescript

await seams.grants.issue({
  endUsers: [user.id],
  amountUnits: String(cents * 10_000n), // Stripe cents → micros
  reason: "top_up",
  idempotencyKey: stripeEvent.id,
})

What the end user hits

Code	Meaning
`insufficient_credit`	Wallet cannot cover the hold; offer a top-up
`spend_limit_exceeded`	Key or bundle cap, not the wallet; wait or raise the cap

This is not a plan allotment. If you later add a Pro tier with monthly credits, that is a separate bundle include; see Credit systems. Markup on paygo stays usage-based.

Model aliases

Create and swap the names callers use.

Routers

How a router attaches to bundles that allow its targets.

Bundles

Markup, sell prices, and spend limits.