Quick start

Waypoint gives a model permission to act on-chain without handing it a private key. You issue a session — a scoped key with a spending cap, a list of allowed functions and an expiry — and your agent calls protocols through it as typed functions.

This page takes you from an empty directory to a signed transaction. Everything below runs against the testnet directory, so nothing here spends real funds.

Install

The SDK ships as a single package with the CLI bundled. Node 20 or later, or any runtime with fetch and Web Crypto.

$ npm install @waypoint/sdk
$ waypoint --version
✓ waypoint 1.4.0

You’ll need three things before the first call:

• A Waypoint account — created on first login, no wallet required.
• A smart account to delegate from. The CLI deploys one on testnet for you.
• Somewhere to keep the session key: an environment variable is fine for local work.

Authenticate

Logging in stores a device token, not a key. Session keys are issued per run and never touch your account.

$ waypoint login
✓ signed in as you@team.dev

# issue a session: 200 USDC, two functions, 24 hours
$ waypoint session start --budget 200 --scope swap,lend
✓ key issued · wpk_8f3c21 · expires in 24h

Your first call

Every protocol in the directory publishes typed functions. You call them by name — there is no ABI to import and no interface to render.

import { Waypoint } from "@waypoint/sdk";

const wp = new Waypoint({ key: process.env.WAYPOINT_KEY });

const tx = await wp.call("helix.swap", {
  in:     "USDC",
  out:    "ETH",
  amount: 120
});

console.log(tx.hash);   // 0x8f3…c21

What comes back

Results are typed and identical every time. There is no page to parse and no state to guess at.

{
  "ok":    true,
  "hash":  "0x8f3…c21",
  "ms":    84,
  "spent": { "amount": 120, "remaining": 80 }
}

Sessions and budgets

One key can carry several budgets. Each budget is enforced by the smart account itself, so a compromised agent still cannot exceed a cap or reach a function that was never switched on.

• Cap. Total spend across the session’s lifetime, denominated in one asset.
• Scope. The functions this key may call — swap, lend, stake, pay.
• Expiry. A wall-clock deadline after which the key stops working on its own.

Budgets can be added to a live session, and any of them can be revoked without touching the others.

// add a second budget to a running session
await wp.budgets.add("wpk_8f3c21", {
  cap:   50,
  asset: "USDC",
  scope: ["stake"],
  ttl:   "6h"
});

// and pull the whole key when you're done
await wp.sessions.revoke("wpk_8f3c21");

Errors

Failures are values, not exceptions. A refused call returns the reason and the numbers behind it, so an agent can decide what to do next without guessing.

{
  "ok": false,
  "error": {
    "code":      "budget_exceeded",
    "limit":     200,
    "attempted": 240
  }
}

The four you’ll meet most often:

• budget_exceeded — the call would spend past the cap. Raise it or split the call.
• scope_denied — the function isn’t in this key’s scope.
• session_expired — the key passed its expiry. Issue a new one.
• unknown_function — no such entry in the directory, usually a version drift.

Next steps

• Sessions overview — budgets, scopes and expiry in full.
• Publishing — put your own protocol in the directory with one schema file.
• SDK reference — every method, with types.