Skip to Content
SDKSDK API Reference

SDK API Reference

This page is a practical method reference for TypeScript and Python SDK usage.

Package reference

  • @beav3r/sdk: core client for offchain guard flows and /onchain/* authorization APIs
  • @beav3r/protocol: shared protocol schemas and hashing primitives
  • @beav3r/protocol-onchain: optional onchain helper utilities for executor integration

Client import and setup

import { Beav3r } from '@beav3r/sdk'
 
const client = new Beav3r({
  apiKey: process.env.BEAV3R_API_KEY,
  baseUrl: process.env.BEAV3R_BASE_URL ?? 'https://staging.server.beav3r.ai',
  agentId: 'my_runtime',
  defaultExpirySeconds: 180
})

Use https://server.beav3r.ai for production.

For the latest onchain support, use the current beta SDK line:

npm install @beav3r/sdk@beta

Typical return shape

Many request methods return:

{
  "status": "pending | approved | executed | denied | rejected | expired",
  "actionId": "act_123",
  "actionHash": "hash_123",
  "reason": "Require approval above 10 USDT",
  "evaluation": {
    "decision": "allow | require_approval | deny",
    "severity": "routine | elevated | critical",
    "reason": "Require approval above 10 USDT"
  }
}

guard() / guard()

Immediate evaluation result without waiting.

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

Common outcomes:

  • executed
  • pending
  • denied

guardAndWait() / guard_and_wait()

Submit and poll until 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

guardOrThrow() / guard_or_throw()

Throw immediately when policy denies.

try {
  const result = await client.guardOrThrow({
    actionType: 'payments.send_usdt',
    payload: { amount: 25 }
  })
  console.log(result.status)
} catch (error) {
  console.error('Denied by Beav3r:', error)
}

requestAction() / request_action()

Lower-level request-style method behind guard.

const result = await client.requestAction({
  actionType: 'payments.send_usdt',
  payload: { amount: 25 }
})

relayAction() / relay_action()

Queue-first behavior; always routes into approval semantics.

const result = await client.relayAction({
  actionType: 'payments.send_usdt',
  payload: { amount: 25 },
  reason: 'Route this transfer to Beav3r for signer review'
})

Onchain methods

Use these with @beav3r/sdk (TypeScript) or beav3r-sdk (Python). For helper utilities around artifact/executor workflows, pair with @beav3r/protocol-onchain (TypeScript) or pip install "beav3r-sdk[onchain]" (Python).

const provisioned = await client.provisionOnchainUser({
  chainId: 84532,
  intendedOwner: '0xYourOwnerAddress'
})
 
const auth = await client.authorizeOnchainAction({
  projectId: process.env.BEAV3R_PROJECT_ID!,
  account: '0xActorAccount',
  to: '0xTokenAddress',
  value: '0',
  data: '0x...',
  chainId: 84532,
  nonce: BigInt(Math.floor(Date.now() / 1000)),
  expiresAt: BigInt(Math.floor(Date.now() / 1000) + 1200),
  executor: '0xExecutorAddress'
})

See First Onchain Script for an end-to-end executor example.

authorizeAndExecute() / authorize_and_execute()

Verify an execution authorization artifact, redeem it server-side, then run your execute callback. Combines redeemExecutionAuthorization + caller-supplied execution in one step.

const result = await client.authorizeAndExecute({
  action,
  artifact,
  audience: 'my-service',
  publicKeys,
  execute: async ({ actionHash, authorization }) => {
    // perform the guarded action here
    return { txHash: '0x...' }
  }
})

Returns { actionId, actionHash, artifactId, authorization, redemption, executionResult }.

getExecutionAuthorizationKeys() / get_execution_authorization_keys()

Fetch the well-known public keys used to verify execution authorization artifacts.

const { items } = await client.getExecutionAuthorizationKeys()
// items: [{ keyId, algorithm, publicKey }]

getActionStatus() / get_action_status()

Read latest status for a known action id.

const status = await client.getActionStatus(actionId)

getAction() / get_action()

Read full action payload + evaluation details.

const action = await client.getAction(actionId)

listPendingActions() / list_pending_actions()

Read pending queue.

const result = await client.listPendingActions()
const scoped = await client.listPendingActions({ deviceId: 'device_123' })

listRecentActions() / list_recent_actions()

Read recent action history.

const result = await client.listRecentActions()
const scoped = await client.listRecentActions({ deviceId: 'device_123' })

listPolicyRules() / list_policy_rules()

Inspect current policy rules.

const result = await client.listPolicyRules()
const scoped = await client.listPolicyRules({ agentId: 'my_runtime' })

Python signer helpers

beav3r-sdk-py also exposes:

  • register_device(device)
  • submit_approval(token)
  • reject_approval(rejection)
  • aliases: BeaverClient, BeaverDeniedError

Start with guardAndWait() / guard_and_wait() for the fastest end-to-end integration.

Last updated on
Request Expiry and Terminal StatesTroubleshooting Basics