Skip to content
HalvorAI mark HalvorAI mark HalvorAI

Quickstart

This guide takes you from nothing to one signed event on the sandbox, using the TypeScript SDK. Sandbox uses test keys (hk_test_...) and never touches real money or live data. For Python, see the Python SDK.

Before you start

Section titled “Before you start”

You need Node.js 20 or later and an agent, or any script, that can tell you about a payment it made.

1. Create a test API key

Section titled “1. Create a test API key”

Sign in to the dashboard and open Developers. Create a key with the events:write scope and copy it. It is shown once. HalvorAI stores only a hash of it.

Terminal window
export HALVOR_API_KEY=hk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Register a source

Section titled “2. Register a source”

A source is one installation of the SDK. It signs every event with its own Ed25519 key, and HalvorAI stores only the public half. The CLI creates the key pair, registers the source, writes .env.local, and sends a test event:

Terminal window
npx @halvorai/ingest init

It prints a link to the dashboard. See the CLI reference for the options. After it runs, .env.local holds HALVOR_API_KEY and HALVOR_SOURCE_KEY. Keep the source key in your secret manager.

3. Send an event from your code

Section titled “3. Send an event from your code”
Terminal window
npm install @halvorai/ingest
import { HalvorClient, withAgentContext } from '@halvorai/ingest';


const halvor = new HalvorClient(); // reads HALVOR_API_KEY and HALVOR_SOURCE_KEY


await withAgentContext(
  {
    agent: { id: 'agt_travel_12', name: 'Travel booking agent' },
    owner: { id: 'own_u_4410', type: 'person', country: 'US' },
    instruction: { id: 'task_8890', text: 'Book a return flight to Austin under $500' },
  },
  async () => {
    halvor.emit({
      type: 'payment.settled',
      payment: {
        payment_id: 'pi_3QxAbCdEfGhIjKlM',
        rail: 'stripe',
        amount: { value: '41200', unit: 'minor', currency: 'USD' },
        status: 'settled',
        rail_ref: { payment_intent: 'pi_3QxAbCdEfGhIjKlM' },
      },
      payee: { type: 'merchant', name: 'Example Airways' },
    });
  },
);


await halvor.flush();

emit returns immediately with an event id and never throws. Events are batched, signed and sent in the background. The instruction text is hashed on your machine and never sent.

4. See it in the dashboard

Section titled “4. See it in the dashboard”

Open Payments. The event appears within a few seconds with its agent, owner, payee and status. Open it to see the signature, its position in the hash chain, and any evidence.

Check without the SDK

Section titled “Check without the SDK”

You can confirm the connection from a terminal. This asks who the key belongs to:

Terminal window
curl https://api.sandbox.halvorai.com/v1/me \
  -H "Authorization: Bearer $HALVOR_API_KEY"

Next steps

Section titled “Next steps”