SDK API Reference

This page is a practical reference for the main @beav3r/sdk methods.

The primary client is:

import { Beav3r } from "@beav3r/sdk";

Basic setup

import { Beav3r } from "@beav3r/sdk";
 
const client = new Beav3r({
  apiKey: process.env.BEAV3R_API_KEY,
  baseUrl: process.env.BEAV3R_BASE_URL ?? "http://localhost:3000",
  agentId: "my_runtime",
  defaultExpirySeconds: 180
});

guard()

Use guard() for a single evaluation result returned immediately.

const result = await client.guard({
  actionType: "payments.send_usdt",
  payload: {
    amount: 25,
    asset: "USDT",
    network: "base",
    recipient: "0x1111111111111111111111111111111111111111"
  }
});

Possible outcomes:

• executed
• pending
• denied

Use it when:

• the runtime already has its own polling loop
• only the first Beav3r decision is needed
• immediate branching on pending vs denied is needed

guardAndWait()

Use guardAndWait() to submit the action and keep polling until a terminal state or timeout.

const result = await client.guardAndWait(
  {
    actionType: "payments.send_usdt",
    payload: {
      amount: 25,
      asset: "USDT",
      network: "base",
      recipient: "0x1111111111111111111111111111111111111111"
    }
  },
  {
    pollIntervalMs: 2000,
    timeoutMs: 5 * 60 * 1000
  }
);

Possible outcomes:

• approved
• executed
• denied
• rejected
• expired
• pending

Use it when:

• the easiest end-to-end flow is needed
• the script should wait for the signer decision
• custom polling logic is not needed

This is the best starting point for most users.

Typical policy pairing for this flow:

• action type: payments.send_usdt
• effect: Require approval
• condition field: amount
• operator: gt
• value: 10

That means a 25 USDT example like the one above should route into approval.

guardOrThrow()

Use guardOrThrow() when a policy denial should behave like an exception in the app.

try {
  const result = await client.guardOrThrow({
    actionType: "payments.send_usdt",
    payload: {
      amount: 25,
      asset: "USDT",
      network: "base",
      recipient: "0x1111111111111111111111111111111111111111"
    }
  });
 
  console.log(result.status);
} catch (error) {
  console.error("Denied by Beav3r:", error);
}

What it does:

• returns normally for executed or pending
• throws Beav3rDeniedError if Beav3r denies the action immediately

Use it when:

• denial should interrupt control flow
• the application already uses exception-based handling

requestAction()

requestAction() is the lower-level method behind guard().

const result = await client.requestAction({
  actionType: "payments.send_usdt",
  payload: {
    amount: 25,
    asset: "USDT",
    network: "base",
    recipient: "0x1111111111111111111111111111111111111111"
  }
});

Use it when:

• the raw request-style method name is preferred
• custom abstractions are being built on top of the SDK

For most product usage, prefer guard().

relayAction()

Use relayAction() when the caller is explicitly sending something into the approval queue rather than asking for immediate allow-or-deny evaluation.

const result = await client.relayAction({
  actionType: "payments.send_usdt",
  payload: {
    amount: 25,
    asset: "USDT",
    network: "base",
    recipient: "0x1111111111111111111111111111111111111111"
  },
  reason: "Route this transfer to Beav3r for signer review"
});

Expected result:

• a pending action record that enters the approval flow

Use it when:

• the integration semantics are “always send for review”
• a bridge-style flow is being implemented

getActionStatus()

Use getActionStatus() to poll the latest status for one action.

const status = await client.getActionStatus(actionId);

Possible statuses:

• pending
• approved
• executed
• denied
• rejected
• expired

Use it when:

• an actionId is already available
• a custom wait loop is being built
• lightweight status checks are preferred

getAction()

Use getAction() for the full action payload and evaluation details for one action.

const action = await client.getAction(actionId);

Use it when:

• the payload is needed for inspection
• the full evaluation result is needed, not just status
• detail views or audit views are being built

listPendingActions()

Use listPendingActions() to get the pending queue.

const result = await client.listPendingActions();

Optional filter:

const result = await client.listPendingActions({ deviceId: "device_123" });

Use it when:

• building a signer inbox
• checking whether a device still has work waiting

listRecentActions()

Use listRecentActions() to get recent action history.

const result = await client.listRecentActions();

Optional filter:

const result = await client.listRecentActions({ deviceId: "device_123" });

Use it when:

• showing recent approvals
• building audit or activity views

listPolicyRules()

Use listPolicyRules() to inspect the current policy rules for the calling scope.

const result = await client.listPolicyRules();

Optional filter:

const result = await client.listPolicyRules({ agentId: "my_runtime" });

Use it when:

• validating policy setup in scripts or internal tools
• debugging why an action was allowed, denied, or routed to approval

Device approval methods

These are mostly for signer or device implementations.

registerDevice()

Registers a signer device using a pairing token and a signed registration challenge.

await client.registerDevice({
  deviceId: "device_123",
  publicKey: "...",
  label: "Personal phone",
  secretKeyBase64: "...",
  pairingToken: "..."
});

submitApproval()

Submits an approval token from a signer device.

await client.submitApproval({
  actionHash: "...",
  deviceId: "...",
  signature: "...",
  expiry: Math.floor(Date.now() / 1000) + 300
});

rejectApproval()

Rejects an action from a signer device.

await client.rejectApproval({
  actionHash: "...",
  deviceId: "..."
});

Which method should I start with?

Start with:

• guardAndWait() for the simplest real integration path

Use:

• guard() to manage pending flows directly
• guardOrThrow() if denial should become an exception
• relayAction() when the integration is explicitly queue-first

Related guides

• Run Your First Script
• Troubleshooting Basics