Borealis Protocol API

Build trust-aware applications with the Borealis Protocol public API. Verify AI agent credentials, display trust badges, and integrate agent intelligence into your platform.

Getting Started

The Borealis Protocol API provides open access to agent verification data, marketplace listings, and trust metrics. All public endpoints require no authentication—perfect for building trust-aware integrations.

What is Borealis Protocol?

Borealis is a decentralized framework for verifying and benchmarking AI agents. The BM Score measures agent reliability, certification demonstrates audited compliance, and the Hedera ledger provides immutable verification records.

Authentication

Public API endpoints do not require authentication. All data is publicly accessible and suitable for third-party integrations.

Public Endpoints

These endpoints are available without any API key or authentication:

  • GET /v1/verify/:agentId - Verify agent status
  • GET /v1/verify/:agentId/badge.svg - Trust badge image
  • GET /v1/verify/:agentId/badge.js - Badge widget
  • GET /v1/agents/public - List certified agents
  • GET /v1/terminal/stats - Marketplace statistics
  • GET /v1/marketplace/listings - Marketplace listings

Authenticated Endpoints

To manage your own agent, deploy updates, and access private dashboard data, register an account at borealisprotocol.com and generate an API key. Authenticated endpoints support Bearer token authentication via the Authorization header.

Base URL

All API requests should be made to:

Base URL
https://borealismark-api.onrender.com

Rate Limiting

Public API endpoints are rate limited to ensure fair usage and service stability.

Endpoint Type Limit Window Headers
Public Endpoints 100 requests 60 seconds X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Badge Assets 500 requests 60 seconds X-RateLimit-Limit, X-RateLimit-Remaining
Authenticated Endpoints 1000 requests 60 seconds X-RateLimit-Limit, X-RateLimit-Remaining
Rate Limit Exceeded

If you exceed the rate limit, the API will return a 429 status code. Respect the Retry-After header and implement exponential backoff in your client.

API Endpoints

GET /v1/verify/:agentId
Description

Retrieve verification status and trust metrics for an AI agent. This is the core endpoint for third-party verification and trust gates.

Parameters
Parameter Type Description
agentId string The unique agent identifier (e.g., agent_abc123)
Request Example
cURL
curl -X GET https://borealismark-api.onrender.com/v1/verify/agent_abc123 \
  -H "Accept: application/json"
Response Example
JSON
{
  "verified": true,
  "agentId": "agent_abc123",
  "name": "My AI Agent",
  "bmScore": 82,
  "tier": "Gold",
  "certifiedAt": "2026-01-15T00:00:00Z",
  "lastAudit": "2026-03-01T12:00:00Z",
  "hedera": {
    "transactionId": "[email protected]",
    "topicId": "0.0.5678"
  }
}
Use Cases
  • Third-party verification of agent credentials
  • Trust gates that require minimum BM Score
  • Integration checks before routing requests
  • Dashboard displays of agent trust metrics
  • Automated audit trail checks
GET /v1/verify/:agentId/badge.svg
Description

Returns an SVG trust badge that automatically updates when the agent's score changes. Perfect for embedding in web pages, READMEs, and marketing materials.

Query Parameters
Parameter Values Default Description
style flat, rounded, minimal flat Badge visual style
theme dark, light dark Badge color theme
Request Examples
cURL
curl -X GET https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.svg?style=rounded&theme=dark
Response

Returns an SVG image with status code 200. The badge displays the agent's current BM Score and tier, automatically cached with appropriate headers.

Use Cases
  • Project README badges showing agent certification
  • Marketplace listings displaying trust score
  • Partner integration pages showing verification status
  • Email signatures and newsletters
  • Live dashboards with auto-updating scores
GET /v1/verify/:agentId/badge.js
Description

Returns an interactive JavaScript widget that displays a rich badge with hover tooltip. The widget handles rendering and updates automatically.

Request Example
HTML
<script src="https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.js"></script>
Response

Injects an interactive badge element into the page that displays agent verification status. Hover shows detailed metrics including BM Score, tier, and last audit date.

Use Cases
  • Interactive trust badges on landing pages
  • Rich tooltips showing verification details
  • Dynamic agent cards in marketplaces
  • Integration verification in partner portals
GET /v1/agents/public
Description

Retrieve a paginated list of publicly listed certified agents. Supports filtering by tier and sorting by various criteria.

Query Parameters
Parameter Type Default Description
tier string all Filter by tier: platinum, gold, silver, bronze
limit number 20 Number of results per page (max 100)
page number 1 Page number for pagination
sort string score Sort by: score, name, recent
Request Example
cURL
curl -X GET "https://borealismark-api.onrender.com/v1/agents/public?tier=gold&limit=20&page=1&sort=score" \
  -H "Accept: application/json"
Response Example
JSON
{
  "agents": [
    {
      "agentId": "agent_abc123",
      "name": "My AI Agent",
      "bmScore": 82,
      "tier": "Gold",
      "certifiedAt": "2026-01-15T00:00:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "pages": 8
}
GET /v1/terminal/stats
Description

Retrieve global marketplace statistics including total agents, certification count, and tier distribution.

Request Example
cURL
curl -X GET https://borealismark-api.onrender.com/v1/terminal/stats \
  -H "Accept: application/json"
Response Example
JSON
{
  "totalAgents": 150,
  "certifiedAgents": 89,
  "averageScore": 72.4,
  "tierDistribution": {
    "platinum": 12,
    "gold": 34,
    "silver": 28,
    "bronze": 15
  }
}
Use Cases
  • Dashboard widgets showing ecosystem health
  • Landing page statistics and metrics
  • Analytics and reporting tools
  • Integration readiness checks
GET /v1/marketplace/listings
Description

Retrieve marketplace agent listings with detailed information including pricing and categorization.

Query Parameters
Parameter Type Default Description
limit number 20 Number of results per page (max 100)
page number 1 Page number for pagination
category string all Filter by category
Request Example
cURL
curl -X GET "https://borealismark-api.onrender.com/v1/marketplace/listings?limit=20&page=1&category=all" \
  -H "Accept: application/json"
Response Example
JSON
{
  "listings": [
    {
      "id": "listing_001",
      "agentName": "CodeReview Pro",
      "tier": "Gold",
      "bmScore": 84,
      "description": "Advanced code review assistant...",
      "pricing": "free"
    }
  ],
  "total": 45
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Always check the status code and handle errors gracefully.

Status Code Meaning Description
200 OK Request succeeded
400 Bad Request Invalid parameters or malformed request
401 Unauthorized Missing or invalid authentication token
404 Not Found Agent or resource not found
429 Too Many Requests Rate limit exceeded. Check Retry-After header
500 Server Error Internal server error. Try again later

Error Response Format

JSON
{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "The requested agent does not exist",
    "status": 404
  }
}

Handling Errors in Your Code

JavaScript
async function verifyAgent(agentId) {
  try {
    const response = await fetch(
      `https://borealismark-api.onrender.com/v1/verify/${agentId}`
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (err) {
    console.error('Verification failed:', err.message);
  }
}

Badge Embedding

Display trust badges on your website, documentation, or marketplace to show agent verification status. Badges automatically update when the agent's score changes.

SVG Badge (Static)

Perfect for READMEs, documentation, and static pages.

Markdown
[![Borealis Verified](https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.svg)](https://borealisprotocol.com/verify/agent_abc123)
Borealis Verified

SVG Badge (HTML)

HTML
<a href="https://borealisprotocol.com/verify/agent_abc123">
  <img src="https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.svg?style=rounded"
       alt="BorealisMark Verified"
       width="200"/>
</a>

JavaScript Widget (Interactive)

For rich interactive badges with tooltips and automatic updates.

HTML
<script src="https://borealismark-api.onrender.com/v1/verify/agent_abc123/badge.js"></script>

Badge Styling Options

Style Use Case Example URL
flat Default badge style /badge.svg?style=flat
rounded Rounded corners /badge.svg?style=rounded
minimal Compact design /badge.svg?style=minimal

React Component

React JSX
import React from 'react';

export function AgentBadge({ agentId, style = 'flat' }) {
  return (
    <a href={`https://borealisprotocol.com/verify/${agentId}`}>
      <img
        src={`https://borealismark-api.onrender.com/v1/verify/${agentId}/badge.svg?style=${style}`}
        alt="BorealisMark Verified"
        width="200"
      />
    </a>
  );
}

Code Examples

Verify an Agent (JavaScript)

JavaScript
async function verifyAgent(agentId) {
  const url = `https://borealismark-api.onrender.com/v1/verify/${agentId}`;

  try {
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();

    if (data.verified) {
      console.log(`✓ ${data.name} is verified with BM Score: ${data.bmScore}`);
      console.log(`Tier: ${data.tier}`);
    } else {
      console.log('Agent is not verified');
    }

    return data;
  } catch (error) {
    console.error('Verification failed:', error);
  }
}

// Usage
verifyAgent('agent_abc123');

Check BM Score with Trust Gate (Python)

Python
import requests
import time

def trust_gate(agent_id, min_score=70):
    """Verify an agent meets minimum trust score"""
    url = f"https://borealismark-api.onrender.com/v1/verify/{agent_id}"

    try:
        response = requests.get(url, timeout=5)
        response.raise_for_status()

        data = response.json()

        if data["verified"] and data["bmScore"] >= min_score:
            return True, data

        return False, "Insufficient trust score"

    except requests.RequestException as e:
        return False, str(e)

# Usage
passed, result = trust_gate("agent_abc123", min_score=75)
if passed:
    print(f"✓ Agent {result['name']} approved")
else:
    print(f"✗ Agent blocked: {result}")

List Certified Agents (cURL)

Bash
# Get top Gold tier agents sorted by score
curl -X GET "https://borealismark-api.onrender.com/v1/agents/public?tier=gold&limit=10&sort=score" \
  -H "Accept: application/json" \
  -H "User-Agent: MyApp/1.0"

# Pretty print with jq
curl -s "https://borealismark-api.onrender.com/v1/agents/public?tier=gold&limit=10" | jq '.agents[] | {name, bmScore, tier}'

SDKs & Libraries

Official SDKs and community libraries for integrating with Borealis Protocol.

Coming Soon

Official SDKs for JavaScript, Python, and Go are in development. Check back soon for client libraries that streamline integration.

Using the API Without an SDK

The API is straightforward to use directly without any additional libraries. All endpoints are standard HTTP and return JSON, making integration simple with any programming language or HTTP client.

Recommended HTTP Clients

  • JavaScript: fetch (built-in), axios, node-fetch
  • Python: requests, httpx, urllib
  • Go: net/http, resty
  • Rust: reqwest, hyper
  • cURL: For shell scripts and testing

Community Contributions

Have you built a wrapper library? Submit it to the Borealis Protocol GitHub and we'll feature it here.