How Do You Integrate BorealisMark into Your AI Agent?

You have built an AI agent. It works. Now you need to answer the question your enterprise buyers, compliance teams, and risk officers will ask: how do we know it behaves the way you claim?

That is what BorealisMark solves. This guide walks you through the complete integration path - from purchasing a BTS License Key, installing the Merlin SDK, submitting behavioral telemetry for scoring, retrieving your BTS, and displaying a publicly verifiable trust badge on your product page.

The full integration takes under an hour. The result is a blockchain-anchored trust credential that can be independently verified by anyone, on-chain, without trusting your word.

What Is BorealisMark?

BorealisMark is the identity and certification layer of the Borealis Protocol ecosystem. Its core product is the BTS - a composite trust rating from 0 to 100 that evaluates an AI agent's behavioral trustworthiness across five weighted dimensions:

Every score update is SHA-256 hashed and committed to the Hedera Hashgraph Consensus Service as an immutable record. No party - including Borealis - can alter a committed score. This is not decorative blockchain usage. It directly addresses the core credibility problem: if someone is going to trust a trust score, the score itself must be tamper-proof.

For a deeper explanation of the scoring methodology, see How Does the Borealis Trust Score Work?

Prerequisites

Before you begin, you need the following:

• A BTS License Key - Purchase one at Borealis Terminal for $39.99. Your key arrives by email immediately after purchase in the format BTS-XXXX-XXXX-XXXX-XXXX. One key binds permanently to one agent.
• Node.js 18+ - The Merlin SDK uses native fetch, which requires Node 18 or later. No additional HTTP client dependencies needed.
• A BorealisMark account - Register at borealismark.com to manage your licenses, view your dashboard, and access purchase history.
• Email verification complete - Your BorealisMark account must have a verified email address before you can activate a license key.

Step 1 - Install the Merlin SDK

The @borealis/merlin-sdk package is a thin TypeScript wrapper around the BorealisMark REST API. It has zero dependencies beyond Node's built-in fetch.

npm install @borealis/merlin-sdk

If you are using TypeScript (recommended), types are included - no separate @types package needed.

Initialize the client once at agent startup and reuse it throughout the agent's lifecycle:

import { MerlinClient } from '@borealis/merlin-sdk';

const merlin = new MerlinClient({
  key: process.env.BTS_LICENSE_KEY!, // 'BTS-XXXX-XXXX-XXXX-XXXX'
});

Store your BTS key in an environment variable - never hardcode it in source. The constructor validates the key format on initialization and throws immediately if it does not match BTS-XXXX-XXXX-XXXX-XXXX.

If you need to point at a custom API URL (for testing), pass it as apiUrl:

const merlin = new MerlinClient({
  key: process.env.BTS_LICENSE_KEY!,
  apiUrl: 'https://borealismark-api.onrender.com', // default
  timeout: 30_000, // ms, default 30s
});

Step 2 - Activate Your BTS Key

Activation is a one-time operation that permanently binds your key to an agent ID. Call it once at first startup, after confirming the key has not already been activated.

const result = await merlin.activate(
  'my-agent-v1',                    // agentId - your unique agent identifier
  'My Production Agent',            // agentName - human-readable name
  'Customer support agent for ...'  // agentDescription - optional
);

if (result.success) {
  console.log('Activated:', result.data?.licenseId);
  console.log('Agent ID:', result.data?.agentId);
  console.log('Slots used:', result.data?.agentSlots.used, '/', result.data?.agentSlots.max);
} else {
  console.error('Activation failed:', result.error);
}

A successful activation returns a licenseId, the bound agentId, the activatedAt Unix timestamp, and your current slot usage (slot caps are tier-based: Standard=3, Pro=10, Elite=20).

If you call activate() a second time with the same key, the API returns an error - the key is already bound. Build a guard in your startup logic to call activation only when needed:

async function ensureActivated(merlin: MerlinClient): Promise {
  const status = await merlin.verify();
  if (status.success && status.data?.status === 'active') {
    return; // already activated, nothing to do
  }
  // First run - activate now
  const result = await merlin.activate('my-agent-v1', 'My Production Agent');
  if (!result.success) {
    throw new Error(`BTS activation failed: ${result.error}`);
  }
}

Step 3 - Submit Telemetry for BTS Computation

Telemetry submission is the core of the integration. You submit structured behavioral data from your agent, and the scoring engine computes a BTS from it, records the result in the database, and anchors the score hash to Hedera.

Understanding the Telemetry Schema

The v3.2 "Pragmatic Trust" telemetry schema maps directly to the five scoring dimensions. Each field feeds a specific factor in the scoring engine:

import type { TelemetryPayload } from '@borealis/merlin-sdk';

// Build your telemetry payload from the batch of events your agent processed
const payload: Omit<TelemetryPayload, 'key'> = {
  batchId: `batch_${Date.now()}`,     // unique per batch
  sequenceStart: 10452,               // first event sequence number in this batch
  sequenceEnd:   10499,               // last event sequence number
  period: {
    from: new Date(batchStartTime).toISOString(),
    to:   new Date(batchEndTime).toISOString(),
  },
  reportingMode: 'self-reported',     // or 'aegis-verified' when using Aegis (independent verification)

  scores: {
    // Constraint Adherence (35%) - one entry per constraint rule
    constraints: [
      {
        constraintId: 'no-pii-access',
        name: 'No access to PII fields',
        severity: 'CRITICAL',         // CRITICAL | HIGH | MEDIUM | LOW
        passed: true,
        evaluationCount: 48,          // how many times this rule was evaluated
      },
      {
        constraintId: 'scope-limit',
        name: 'Restrict to allowed domains',
        severity: 'HIGH',
        passed: true,
        evaluationCount: 48,
      },
    ],

    // Decision Transparency (20%) - one entry per significant decision
    decisions: [
      {
        decisionId: 'd_10452',
        timestamp: 1711212130,
        reasoningDepth: 3,            // 0 (no reasoning) to 5 (full chain)
        confidence: 0.92,             // 0 to 1
        hasReasoningChain: true,
        wasOverridden: false,
      },
    ],

    // Behavioral Consistency (20%) - one entry per input class your agent handles
    behaviorSamples: [
      {
        inputClass: 'customer_query', // category of input
        sampleCount: 48,
        outputVariance: 0.08,         // 0 = perfectly consistent, 1 = fully random
        deterministicRate: 0.94,      // fraction of outputs that matched expected patterns
      },
    ],

    // Anomaly Rate (15%)
    anomalySummary: {
      totalActions: 48,
      anomalyCount: 1,               // flagged or out-of-distribution outputs
    },

    // Audit Completeness (10%)
    auditCompleteness: {
      expectedLogEntries: 48,
      actualLogEntries: 48,           // should equal expected if all ops are logged
    },
  },

  // Evidence block - cryptographic commitment to the full event log
  evidence: {
    totalEventsInBatch: 48,
    batchHash: computeSHA256(fullEventLog), // SHA-256 of your complete event log
    eventSample: [
      {
        sequenceId: 10452,
        timestamp: new Date().toISOString(),
        inputHash:  sha256(inputData),
        outputHash: sha256(outputData),
        actionType: 'tool_call',
        toolName: 'database_query',
        executionTimeMs: 840,
      },
    ],
  },
};

Submitting the Batch

const response = await merlin.submitTelemetry(payload);

if (response.success && response.data) {
  const { btsScore, hedera, suspicionFlags } = response.data;

  console.log(`BTS: ${btsScore.display}/100 (${btsScore.creditRating})`);
  console.log(`Trust ceiling: ${btsScore.trustCeiling}/100`);

  if (hedera) {
    console.log(`Hedera TX: ${hedera.transactionId}`);
    console.log(`Anchored at: ${hedera.consensusTimestamp}`);
  }

  if (suspicionFlags.flagCount > 0) {
    console.warn(`Suspicion flags: ${suspicionFlags.message}`);
  }
} else {
  console.error('Telemetry submission failed:', response.error);
}

The Self-Reported Trust Ceiling

When reportingMode is 'self-reported', the scoring engine applies a trust ceiling of 85 out of 100. This means your BTS cannot exceed 85 regardless of how perfect your submitted metrics are. The ceiling exists because self-reported data cannot be independently verified - a developer could in principle fabricate ideal telemetry.

To achieve scores above 85, the protocol defines Aegis verification (formerly known as Sidecar) - independent assessment of your agent's behavior by separate audit systems rather than self-report. When reportingMode is 'aegis-verified', the ceiling is removed and scores up to 100 are achievable. Aegis verification is part of the Borealis audit pipeline that Merlin keys unlock; see the Borealis Terminal for current capabilities.

Submission Cadence

Submit one batch per meaningful operational period - typically every 15 to 60 minutes of active processing, or once you have accumulated at least 50 agent events. Do not submit per-event: the schema is designed for batched data. The server tracks sequenceStart and sequenceEnd to detect gaps in your audit trail, so keep your sequence numbers contiguous.

Step 4 - Retrieve Your Trust Score

There are two ways to retrieve a score. Use verify() for internal runtime checks (requires your BTS key). Use getScore() for public-facing lookups by agent ID (no key required).

Runtime Heartbeat with verify()

Call verify() on a regular schedule - every 5 to 15 minutes - to confirm your key is still active and pull the latest cached score. This is also how your agent detects revocation and should shut down gracefully:

// Set up a heartbeat interval
setInterval(async () => {
  const status = await merlin.verify();

  if (!status.success || status.data?.status !== 'active') {
    console.error('BTS key is no longer active. Status:', status.data?.status);
    // Gracefully stop trust-certified operations
    agent.setCertificationStatus('suspended');
    return;
  }

  const score = status.data?.btsScore;
  if (score) {
    console.log(`Current score: ${score.display}/100 (${score.creditRating})`);
  }
}, 10 * 60 * 1000); // every 10 minutes

Public Score Lookup with getScore()

Anyone can look up any agent's score by agent ID. This is what powers the public verification page and third-party audits:

// No key needed - public endpoint
const score = await merlin.getScore('my-agent-v1');

if (score.success && score.data) {
  const { agentName, btsScore, license } = score.data;
  console.log(`${agentName}: ${btsScore?.display}/100 (${btsScore?.creditRating})`);
  console.log(`Key prefix: ${license.keyPrefix}`);
  console.log(`Activated: ${new Date(license.activatedAt * 1000).toISOString()}`);
  console.log(`Hedera proof: ${btsScore?.hedera?.transactionId}`);
}

Step 5 - Display the BTS Trust Badge

Once your agent has a BTS, display a trust badge on your product page or documentation. Always fetch the score live - never hardcode it. Link the badge to the public verification page so visitors can independently confirm the score on-chain.

// Fetch and render a trust badge (vanilla JS example)
async function renderTrustBadge(agentId, containerEl) {
  const API = 'https://borealismark-api.onrender.com';
  const res = await fetch(`${API}/v1/licenses/public/${agentId}`);
  const json = await res.json();

  if (!json.success || !json.data?.btsScore) {
    containerEl.textContent = 'Score unavailable';
    return;
  }

  const { display, creditRating, hedera } = json.data.btsScore;
  const verifyUrl = `https://borealismark.com/verify/${agentId}`;

  containerEl.innerHTML = `
    <a href="${verifyUrl}" target="_blank" rel="noopener"
       style="display:inline-flex;align-items:center;gap:10px;
              padding:10px 16px;border-radius:6px;
              background:#1a1a23;border:1px solid #2a2a35;
              text-decoration:none;font-family:sans-serif;">
      <span style="font-size:1.4rem;font-weight:700;color:#ffffff;">
        ${display}
      </span>
      <span style="display:flex;flex-direction:column;gap:2px;">
        <span style="font-size:0.75rem;font-weight:700;color:#d4a853;
                     letter-spacing:0.05em;">BTS SCORE</span>
        <span style="font-size:0.72rem;color:#a8a39a;">
          ${creditRating} • Verified on Hedera
        </span>
      </span>
    </a>
  `;
}

// Usage
renderTrustBadge('my-agent-v1', document.getElementById('trust-badge'));

Link the badge to your agent's public verification profile on BorealisMark. Visitors can confirm the score, view the Hedera transaction ID, and independently verify the on-chain commitment without relying on your display.

API Endpoint Reference

The Merlin SDK wraps four endpoints. If you are integrating in a language other than TypeScript, call these directly with any HTTP client. All requests go to https://borealismark-api.onrender.com.

POST /v1/licenses/activate

Permanently binds a BTS key to an agent. One-time operation.

// Request
{
  "key":              "BTS-XXXX-XXXX-XXXX-XXXX",
  "agentId":          "my-agent-v1",
  "agentName":        "My Production Agent",
  "agentDescription": "Optional description"
}

// Response (success)
{
  "success": true,
  "data": {
    "licenseId":   "lic_abc123",
    "agentId":     "my-agent-v1",
    "status":      "active",
    "activatedAt": 1711212130,
    "agentSlots":  { "used": 1, "max": 3 }
  }
}

POST /v1/licenses/verify

Heartbeat check. Returns current key status and the latest cached BTS score.

// Request
{ "key": "BTS-XXXX-XXXX-XXXX-XXXX" }

// Response (success)
{
  "success": true,
  "data": {
    "licenseId":      "lic_abc123",
    "status":         "active",       // active | revoked | suspended | terminated
    "agentId":        "my-agent-v1",
    "agentName":      "My Production Agent",
    "scoring":        true,
    "verifyCount":    142,
    "lastVerifiedAt": 1711212130,
    "btsScore": {
      "total":        870,
      "display":      87,
      "creditRating": "A+",
      "breakdown": {
        "constraintAdherence":   306,
        "decisionTransparency":  178,
        "behavioralConsistency": 182,
        "anomalyRate":           130,
        "auditCompleteness":      98,
        "total":                 894
      },
      "computedAt": 1711212000,
      "hedera": {
        "topicId":            "0.0.10382961",
        "transactionId":      "[email protected]",
        "sequenceNumber":     47,
        "consensusTimestamp": "2026-03-23T14:00:01Z"
      }
    }
  }
}

POST /v1/licenses/telemetry

Submit a telemetry batch for BTS computation. Returns the new score and Hedera proof.

The full request schema is the TelemetryPayload type shown in Step 3 above. The key field is added automatically by the SDK. The response mirrors the TelemetryResponse type and includes the new btsScore object with breakdown, suspicionFlags (Layer 2 statistical detection), and the hedera proof block.

GET /v1/licenses/public/:agentId

Public endpoint. No authentication required. Returns the agent's current BTS score, credit rating, and Hedera proof. Used for badge rendering and third-party verification.

// Response (success)
{
  "success": true,
  "data": {
    "agentId":   "my-agent-v1",
    "agentName": "My Production Agent",
    "btsScore": {
      "total":        870,
      "display":      87,
      "creditRating": "A+",
      "breakdown":    { ... },
      "computedAt":   1711212000,
      "hedera": {
        "topicId":            "0.0.10382961",
        "transactionId":      "[email protected]",
        "sequenceNumber":     47,
        "consensusTimestamp": "2026-03-23T14:00:01Z"
      }
    },
    "license": {
      "keyPrefix":    "BTS-XXXX",
      "status":       "active",
      "activatedAt":  1710000000,
      "verifyCount":  142
    }
  }
}

Rate Limits and Best Practices

Rate Limits

Telemetry Best Practices

Keep sequence numbers contiguous. The scoring engine tracks gaps between sequenceStart and sequenceEnd across batches to compute audit completeness. If your sequence numbers jump, the gap is counted as missing log entries and reduces your audit completeness sub-score.

Include at least one event sample per batch. The evidence.eventSample array provides cryptographic evidence that the batch hash is real. Submitting an empty sample array is valid but reduces the credibility signal that statistical analysis relies on for Layer 2 anti-gaming detection.

Report realistic metrics. The server runs statistical analysis (Layer 2 anti-gaming) on every batch. Submissions with suspiciously perfect metrics - all constraints passing with 100% consistency, zero anomalies, perfect audit completeness, across every batch - are flagged automatically. Real agents have natural variance. A few constraint evaluations near the boundary, a handful of lower-confidence decisions, and an occasional anomaly are expected and healthy signals.

Hash your event log correctly. The evidence.batchHash should be a SHA-256 hash of your complete batch event log before sampling. This is a commitment proof. Aegis (formerly known as Sidecar) - the independent verification layer - compares this hash against independently observed events.

Handle verify() failures gracefully. Network timeouts or API errors on verify() should not cause your agent to stop. Only an explicit status: 'revoked' or status: 'terminated' response should trigger a shutdown. Build retry logic with exponential backoff for transient failures.

Store your BTS key as a secret. Your BTS key is the identity credential for your agent. Store it in your secrets manager or environment variable system - never commit it to source control. The SHA-256 hash of the key is stored in the Borealis database; the raw key is transmitted exactly once in the activation email and from that point forward only in API calls over HTTPS.

Credit Rating Thresholds

Use these thresholds to understand what score range your integration is targeting:

Public Verification

Every agent with a BTS License Key has a public verification profile on BorealisMark. The URL pattern is:

https://borealismark.com/verify/{agentId}

This page shows the agent's current BTS, credit rating, score breakdown across all five dimensions, Hedera transaction ID, and the consensus timestamp of the most recent score anchor. It is publicly accessible - no login required - and the data can be independently confirmed by querying the Hedera public mirror node directly.

Link your trust badge to this page so that enterprise buyers, compliance teams, and end users can verify your agent's trust credentials without relying on your claims.

Further Reading

• How Does the Borealis Trust Score Work? - Full methodology documentation with formula, weights, and credit rating tiers
• How Do You Certify Your First AI Agent on BorealisMark? - Dashboard walkthrough and certification audit process
• Why Does Trust Anchoring on Hedera Hashgraph Matter? - Deep dive into the blockchain layer
• What Are the Best Constraint Design Patterns for AI Agents? - Engineering patterns to maximize constraint adherence scores
• BTS - Glossary definition with worked examples
• BTS License Key - Glossary definition and key lifecycle
• AI Trust Score - Conceptual overview for non-technical stakeholders

Frequently Asked Questions

What is the BTS License Key and why do I need one?

A BTS (Borealis Trust Standard) License Key is a unique credential in the format BTS-XXXX-XXXX-XXXX-XXXX that binds your AI agent to the Borealis trust network. It is the identity layer for your agent: once activated, your key is permanently bound to a single agent ID and cannot be transferred. You need one to submit telemetry for BTS computation, receive a Hedera-anchored trust certificate, and display a verified trust badge. Keys are purchased at Borealis Terminal for $39.99 per agent.

What is the self-reported trust ceiling?

When you submit telemetry with reportingMode: 'self-reported', your BTS is capped at 85 out of 100. This ceiling exists because self-reported data cannot be independently verified. To achieve scores above 85, the protocol uses Aegis verification (formerly known as Sidecar) - independent assessment of your agent's behavior by separate audit systems rather than self-report. When reportingMode is 'aegis-verified', the ceiling is removed. The ceiling is a trust signal, not a limitation.

How often should I submit telemetry?

Submit one telemetry batch per meaningful operational period - typically every 15 to 60 minutes of active processing, or once you have accumulated at least 50 agent events. Do not submit per-event: the scoring engine expects batched data. Call verify() on a separate heartbeat schedule every 5 to 15 minutes to confirm your key status and retrieve the latest cached score without triggering a full recompute.

How do I display a BTS trust badge on my website?

Fetch your agent's public score from GET /v1/licenses/public/:agentId. The response includes the BTS display value, credit rating, and the Hedera transaction ID as proof. Render these values as a badge and link it to your agent's public verification profile at borealismark.com/verify/{agentId}. Always fetch the score live - never hardcode it - so your badge reflects the current rating.

What happens if my BTS key is revoked?

If your BTS key is revoked, the verify() call returns status: 'revoked'. Your agent should detect this and cease trust-certified operations. The revocation is recorded immutably on Hedera, and your agent's public profile shows FLAGGED or inactive status. A revoked key cannot be reactivated - you would need to purchase a new key and bind it to a new agent ID.

Can I use the BorealisMark API directly without the SDK?

Yes. The Merlin SDK is a thin TypeScript wrapper around standard REST endpoints. Every method maps to a single API call: activate() calls POST /v1/licenses/activate, verify() calls POST /v1/licenses/verify, submitTelemetry() calls POST /v1/licenses/telemetry, and getScore() calls GET /v1/licenses/public/:agentId. You can call these directly from Python, Go, or any HTTP client.

What is the difference between the BTS and a standard AI benchmark?

Standard AI benchmarks measure capability - accuracy, speed, task completion rate. The BTS measures behavioral trustworthiness: whether the agent follows its defined constraints (35%), produces auditable reasoning (20%), behaves consistently over time (20%), avoids anomalous outputs (15%), and maintains complete audit coverage (10%). A highly capable agent that ignores its constraints scores poorly on the BTS. The two dimensions are complementary, not the same thing.

Ready to get your BTS key and start the integration? Purchase at Borealis Terminal. Manage your licenses and view your BTS dashboard at borealismark.com.