# Quickstart

Source: https://docs.orbytelabs.com/quickstart

Configure a feature, fund a wallet, and check and track your first usage.

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 [#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:

```dotenv
ORBYTE_API_KEY=cr_secret_your_key
```

Keep this file out of version control. [Authentication](/authentication) explains scopes and separate runtime keys.

## 2. Add the SDK [#2-add-the-sdk]

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

```sh
pnpm add @orbytelabs/credit
```

The package includes the `orbyte` CLI and the server SDK. For another language, follow [the HTTP version below](#use-the-http-api).

## 3. Define your prices [#3-define-your-prices]

Create `orbyte.config.ts` in your app:

```ts
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 [#4-deploy-the-catalog]

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

```sh
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](/environments) before using a Production key.

## 5. Fund, check, and track [#5-fund-check-and-track]

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

```ts
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](/sdk).

`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 [#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 [#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`.

```sh
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:

```sh
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](/checking-and-tracking), [wallets and top-ups](/wallets-and-topups), or [AI SDK](/integrations/ai-sdk).