SDK reference

Source: packages/sdk

A thin, typed HTTP client. Every method here is a direct wrapper around one REST call — nothing here is a framework, a UI, or a required flow.

Install and instantiate

@waysafe/sdk is real, public source — packages/sdk in this repo, the same package the quickstart above already ran, straight from a clone. It isn’t published to npm yet because there’s no hosted API yet for a published package to point at — nothing to publish for, not something being withheld. Once a hosted deployment exists, this is what installing and pointing it at one will look like:

# not yet published -- this is what it will look like once a hosted API exists
npm install @waysafe/sdk

import { Waysafe } from "@waysafe/sdk";

const waysafe = new Waysafe({
  baseUrl: "https://api.your-waysafe-deployment.example",
  apiKey: process.env.WAYSAFE_API_KEY, // an org or agent credential
});

Method reference

The public surface of @waysafe/sdk. For the full request/response shapes on the calls that decide whether money moves, see the raw REST reference below.

Raw REST reference

The SDK is a thin wrapper — this is the wire format underneath, for the two calls that decide whether money moves. Shapes below are transcribed from apps/api/src/server.ts and packages/core/src/domain.ts.

POST /v1/authorizations

Request body:

{
  "agent_id": "agt_...",
  "principal_id": "prin_...",
  "mandate_id": "mdt_...",            // optional -- pins evaluation to one mandate
  "action": {
    "amount": 4200,                    // integer minor units -- $42.00, never a float
    "currency": "USD",
    "merchant": {
      "name": "Staples",               // agent's own claims -- optional, any/all of these
      "domain": "staples.com",
      "psp_account": "acct_...",
      "network_mid": "...",
      "mcc": "5943",
      "onchain_address": "0x..."
    },
    "category": "office_supplies",     // optional
    "description": "Copier paper, 10 reams",  // optional, shown on the receipt
    "attestations": {}                 // optional agent claims, evaluated as claims not facts
  },
  "idempotency_key": "a-client-generated-key-8-255-chars",  // optional, required in production
  "context": {}                        // optional, arbitrary caller context recorded on the receipt
}

merchant carries only what the agent asserts on this call. Which field a value sits in never upgrades its trust — a rail-attested psp_account or network_mid (one the payment rail’s own callback supplied, not one the agent typed here) verifies; the same field asserted directly on this request caps out at STEP_UP, exactly like an unverified name.

Trust belongs to each identifier, not to the merchant as a whole. Sending a real domain alongside an account id of your own does not launder the account id: a match produces ALLOW only when the identifier that matched is itself verified and no identifier on the request is unverified. The STEP_UP_MERCHANT_UNVERIFIED reason names which one failed, so a receipt distinguishes a laundered sibling from a wholly unknown merchant.

On the WebAuthn ceremony routes, a challenge carries the purpose it was issued for and that purpose is authoritative: answering an authentication challenge with a registration response (or the reverse) is a 400 ({"error":"challenge_purpose_mismatch"}), never silently accepted. Enrolling a second passkey for a principal that already has one additionally requires a fresh prior authentication with an existing credential.

Response status: 201 on a fresh decision, 200 if idempotency_key matches a prior request and the stored result is replayed, 404 ({"error":"no_active_mandate"}) if no active mandate covers this request, 409 ({"error":"idempotency_conflict"}) if the same key was reused with a different body.

The three decision shapes, all the same receipt envelope:

// decision: "ALLOW"
{
  "id": "auth_...",
  "actor_kind": "agent",               // or "instrument" for a rail-initiated decision
  "agent_id": "agt_...",
  "instrument_id": null,
  "principal_id": "prin_...",
  "mandate_id": "mdt_...",
  "mandate_version_id": "mdv_...",
  "policy_hash": "...",
  "decision": "ALLOW",
  "status": "AUTHORIZED",
  "reasons": [{ "code": "ALLOW_WITHIN_MANDATE", "message": "..." }],
  "action": { /* echoes the request's action */ },
  "merchant": { /* the engine's resolved view -- trust level, refs */ },
  "idempotency_key": "...",
  "step_up_expires_at": null,
  "created_at": "2026-09-16T03:14:03.431Z",
  "decided_at": "2026-09-16T03:14:03.431Z"
}

// decision: "DENY" -- same envelope, status: "DENIED".
// reasons can carry more than one code: a request can violate several
// constraints at once (e.g. an unlisted merchant AND over the per-
// transaction limit), and every one that applies is returned, not just
// the first.
"reasons": [
  { "code": "DENY_MERCHANT_NOT_ALLOWLISTED", "message": "..." },
  { "code": "DENY_TRANSACTION_LIMIT_EXCEEDED", "message": "..." }
]

// decision: "STEP_UP" -- status: "PENDING_STEP_UP", step_up_expires_at
// set. Resolved at POST /v1/authorizations/:id/step-up (approve/decline);
// approving does not execute -- POST .../execute is the separate step.
"status": "PENDING_STEP_UP",
"step_up_expires_at": "2026-09-16T03:29:03.431Z"

POST /v1/mandates/compile

Request body:

{
  "intent_text": "Spend up to $500/month on office supplies from Amazon or Staples.",
  "timezone": "America/New_York",      // optional, defaults from the environment
  "currency": "USD",                   // optional
  "default_ttl_hours": 720             // optional
}

Three response shapes, all HTTP 200 except failed:

// status: "compiled"
{ "status": "compiled", "policy": { /* ... */ }, "policy_hash": "...",
  "confirmation": { /* ... */ }, "diagnostics": { "compiler": "...", "attempts": 1, "duration_ms": 812 } }

// status: "needs_clarification" -- HTTP 200, not an error. Asking is a
// valid, expected outcome: the compiler never invents a spending ceiling
// the principal didn't state.
{ "status": "needs_clarification",
  "clarifications": [
    { "path": "/limits/per_transaction", "question": "What's the most this can spend in one transaction?",
      "suggested_default": 15000, "rationale": "The instruction gave a monthly cap but no per-transaction limit." }
  ],
  "draft": { /* best-effort partial policy */ }, "diagnostics": { /* ... */ } }

// status: "failed" -- HTTP 422, the only error status of the three.
{ "status": "failed", "error": "policy_compilation_failed", "issues": [ /* ... */ ], "diagnostics": { /* ... */ } }

GET /v1/evidence/public-key

No credential required — a third party auditing a receipt has none. One signing key covers every organization on a given deployment, so there’s one key to publish, not one per tenant. Pin this value once verified out-of-band; a server that could change it at will could sign anything.

{ "algorithm": "Ed25519", "public_key": "MCowBQYDK2VwAyEA..." }

Pair with GET /v1/evidence (returns the same EvidenceRecord[] shape listEvidence() does) and verifyEvidenceIndependently — or its self-contained node:crypto equivalent — to verify locally, with zero trust in the server that produced the data. See /proof for a worked example against one real captured run.

Reason codes

Source: packages/core/src/reason-codes.ts

A public API (additive-only, never renamed) — every decision carries at least one of these. Branch on the code, not the description. Source: packages/core/src/reason-codes.ts.

Evidence event types

Every type this codebase appends to the signed chain, and what each attaches to. A chain is organization-scoped: one sequence, one hash link per entry, with subject_type and subject_id naming what the entry is about.

Decisions made through the API are in this chain too. That was not true until a second adversarial review found it: the rail-initiated paths each appended their own decision evidence, and POST /v1/authorizations appended nothing. A step-up that expires still writes no event. That is a known gap, named in the threat model.