DOCUMENTATION

Beomz Developer Docs

Everything you need to integrate Beomz into your AI agent — from zero to on-chain verdicts in under 10 minutes.

Install

Add the Beomz SDK to your project. Supports TypeScript and Python out of the box. The SDK is published to npm and PyPI.

# TypeScript / Node.js
npm install @beomz/sdk

# Python
pip install beomz

Authenticate

Pass your NEAR account ID and private key. The SDK handles key management and signs on-chain verification requests automatically.

import { BeomzClient } from "@beomz/sdk"

const beomz = new BeomzClient({
  network: "testnet",           // "testnet" | "localnet"
  accountId: process.env.BEOMZ_DEMO_ACCOUNT_ID!,
  privateKey: process.env.BEOMZ_DEMO_PRIVATE_KEY!,
  oracleContractId: "oracle.beomz.testnet",
  tokenContractId: "token.beomz.testnet",
  stakingContractId: "staking.beomz.testnet",
})

Scan a contract

Verify any EVM contract address before interacting with it. Beomz checks for honeypot traps, ownership renouncement, and rug-pull risk patterns.

const verdict = await beomz.verify({
  type: "contract_address",
  chain: "base",
  address: "0xdeadbeef00000000000000000000000000000001",
})

console.log(verdict.result)          // "Safe" | "Risky" | "Scam" | "Pending"
console.log(verdict.confidence_score) // 0.0 – 1.0
console.log(verdict.ai_summary)       // Human-readable explanation
console.log(verdict.policy)           // "allow" | "require_human" | "require_escrow" | "block"

Verify an agent identity

Before hiring or interacting with an agent on any marketplace, verify its registered identity and reputation on-chain.

const verdict = await beomz.verify({
  type: "agent_identity",
  registry: "market.near.ai",
  agent_id: "data-feed-provider.near",
})

Verify a job posting

Check that a job posted on a marketplace is legitimate — not a sybil post or scam listing — before bidding or accepting.

const verdict = await beomz.verify({
  type: "job_posting",
  marketplace: "market.near.ai",
  job_id: "demo-job-rust-contract-001",
})

Verify a URL

Block phishing links and lookalike domains before your agent sends them to users or uses them in any automated flow.

const verdict = await beomz.verify({
  type: "url",
  url: "https://billing.somedomain.tld/pay/123",
})

Verify a code artifact

Scan a commit SHA before triggering CI/CD. Beomz detects malicious dependencies, backdoors, and supply-chain injections.

const verdict = await beomz.verify({
  type: "code_artifact",
  repo: "acme/payments",
  commit_hash: "abc1234deadbeef",
})

Verify a service offering

Before purchasing a data feed or API service, verify the provider identity and the specific service offering on-chain.

const verdict = await beomz.verify({
  type: "service_offering",
  provider_id: "market.near.ai",
  service_id: "weather-feed-v2",
})

Verify an intent digest

Hash a governance proposal or transaction payload and submit the digest to Beomz before signing. Catches malformed or injected payloads.

import { createHash } from "crypto"

const payload = JSON.stringify({ proposal_id: 88, action: "transfer" })
const payloadHash = createHash("sha256").update(payload).digest("hex")

const verdict = await beomz.verify({
  type: "intent_digest",
  action_type: "dao_vote",
  payload_hash: payloadHash,
})

Handle policy: require_human / require_escrow

The SDK surfaces policy recommendations alongside verdicts. Respect them in your agent's decision loop to remain compliant with Beomz risk policy.

const verdict = await beomz.verify(subject)

switch (verdict.policy) {
  case "allow":
    await executeAction()
    break
  case "require_human":
    await notifyHuman("Approval required before proceeding")
    break
  case "require_escrow":
    await holdInEscrow(action)
    break
  case "block":
    throw new Error(`Action blocked: ${verdict.ai_summary}`)
}

Get agent reputation

Fetch a historical reputation score for any registered agent. The score aggregates past verdicts, incident history, and stake weight.

const rep = await beomz.getAgentReputation(
  "market.near.ai",           // registry
  "data-feed-provider.near"   // agent_id
)

console.log(rep.reputation_score)  // 0.0 – 1.0
console.log(rep.total_scans)
console.log(rep.last_verified_at)

Errors

The SDK throws typed errors for timeout, insufficient balance, and oracle failures. Wrap calls in try/catch and handle gracefully.

import { BeomzTimeoutError, BeomzBalanceError } from "@beomz/sdk"

try {
  const verdict = await beomz.verify(subject, { timeoutMs: 90_000 })
} catch (err) {
  if (err instanceof BeomzTimeoutError) {
    console.error("Oracle did not respond in time")
  } else if (err instanceof BeomzBalanceError) {
    console.error("Insufficient BEOMZ balance — replenish your wallet")
  } else {
    throw err
  }
}