Quickstart

This guide charges one credit for an API request. You will create a catalog, add 100 credits to a wallet, check access, and record one request.

1. Choose an application and create a key

Open the Credit dashboard and select your workspace. Start in Development using the application selector. In Developers, open API keys and create a key with the Setup and ingestion preset. Copy its secret when it appears; it is shown once.

The key identifies your application. The SDK and CLI connect to https://api.orbytelabs.com automatically; no API URL configuration is needed.

Set your API key on the server. For local CLI commands, save it in .env.local beside your config:

ORBYTE_API_KEY=cr_secret_your_key

Keep this file out of version control. Authentication explains scopes and separate runtime keys.

2. Add the SDK

The TypeScript SDK requires Node.js 24 or later. Install it in your application:

pnpm add @orbytelabs/credit

The package includes the orbyte CLI and the server SDK. For another language, follow the HTTP version below.

3. Define your prices

Create orbyte.config.ts in your app:

import { credit, feature, Orbit, usd } from "@orbytelabs/credit";

export const credits = credit("credits", "Credits").worth(usd("0.01"));

export default Orbit({
  features: {
    "api-call": feature("API call", "request", credits(1)),
    inference: feature(
      "Inference",
      "call",
      usd
        .markup("10%", (data: { costUsd: string }) => data.costUsd)
        .in(credits),
    ),
  },
});

The feature map defines stable keys. api-call costs one credit. The optional inference example converts a provider cost plus 10% into credits valued at $0.01 each. A $0.20 provider cost would charge 22 credits. This valuation defines a price calculation; it does not exchange money.

4. Deploy the catalog

From the directory containing your config, preview the changes and then apply them:

pnpm exec orbyte deploy --dry-run
pnpm exec orbyte deploy

The CLI prints the organization and application it will change. It creates or updates credit and feature definitions and writes _orbyte.ts in src if that directory exists, otherwise beside the config. Include this file in your TypeScript project and commit it. It types feature names in check and track without a runtime config import. Repeating deployment with the same config does not duplicate the catalog. Removing an entry from the config does not delete its stored history.

Catalog deployment does not start your app or fund wallets. See environments and deployment before using a Production key.

5. Fund, check, and track

Run this in your server code after loading the API key above:

import { check, credit, getWallet, topup, track } from "@orbytelabs/credit";

const identity = "customer_123";
const credits = credit("credits");

await topup(identity, credits(100), {
  idempotencyKey: "welcome_customer_123",
});

const access = await check("api-call", identity);
if (!access.allowed) throw new Error("Insufficient credits.");

// Perform the billable work here.
const usage = await track("api-call", identity, {
  id: "request_123",
});

console.log(usage.status);
console.log(await getWallet(identity));

The first deposit creates the wallet. The first successful track returns status: "accepted" and leaves 99 credits. Repeating the same deposit key and event ID with the same input does not add or deduct credits again. Use a new event ID for each new request.

The SDK runtime reads process environment variables. Unlike the CLI, it does not load .env.local itself. Load the file through your framework or runner, or supply apiKey in the call options. See the SDK reference.

check reads affordability without reserving credits. track checks the balance again when it writes the charge. Handle a failed track even when the earlier check allowed the action.

6. Inspect the result

In Wallets, open customer_123. Select Credits to see its balance, usage, and top-up history. The Overview page also shows the charge under API call. Keep the application selector on Development to see the data created with this key.

Use the HTTP API

These requests reproduce the fixed-price example without the SDK. Use a fresh Development catalog, or reuse existing credits and api-call entries instead of recreating them.

Set ORBYTE_API_KEY in your shell. Shell commands do not automatically read .env.local.

export ORBYTE_API_KEY='cr_secret_your_key'

curl --fail-with-body "https://api.orbytelabs.com/v1/credits" \
  -H "Authorization: Bearer $ORBYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"key":"credits","name":"Credits","unit":"credits"}'

curl --fail-with-body "https://api.orbytelabs.com/v1/features" \
  -H "Authorization: Bearer $ORBYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"key":"api-call","name":"API call","unit":"request","creditKey":"credits","costNanocredits":"1000000000"}'

curl --fail-with-body "https://api.orbytelabs.com/v1/deposits" \
  -H "Authorization: Bearer $ORBYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"identity":"customer_123","creditKey":"credits","amountNanocredits":"100000000000","idempotencyKey":"welcome_customer_123"}'

curl --fail-with-body "https://api.orbytelabs.com/v1/check" \
  -H "Authorization: Bearer $ORBYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"identity":"customer_123","feature":"api-call"}'

Read the check response and continue only when allowed is true. After performing the work, record usage:

curl --fail-with-body "https://api.orbytelabs.com/v1/events" \
  -H "Authorization: Bearer $ORBYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"id":"request_123","identity":"customer_123","feature":"api-call"}'

curl --fail-with-body "https://api.orbytelabs.com/v1/wallets/customer_123" \
  -H "Authorization: Bearer $ORBYTE_API_KEY"

The credits balance should be "99000000000" nanocredits. One credit equals one billion nanocredits. All HTTP amounts use decimal strings.

Continue with checking and tracking, wallets and top-ups, or AI SDK.