> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OTR trust verification REST API reference

> Complete technical documentation for the OTR trust verification API — endpoints, request format, response structure, and integration examples

# REST API Reference

## 6.1 API Overview

The OTR REST API lets AI agents, developers, and platforms query trust scores for any domain. An anonymous tier is available with no API key required for light use. Higher-volume and production usage is served by the versioned v1 API at `api.orbexa.io`.

**Base URL (anonymous, main site)**: `https://orbexa.io/api/otr/verify/:domain` — 5 requests per IP per 24 hours.

**Base URL (versioned, Bearer or x402)**: `https://api.orbexa.io/v1/otr/*` — per-endpoint USDC pricing. New accounts receive a one-time signup grant of 50 units + \$5 credit valid for 90 days.

**Key features**:

* Anonymous tier: 5 requests per IP per 24 hours on the main site — no API key required
* Production usage via `api.orbexa.io/v1/*` — Bearer key or x402 payment header (per-endpoint USDC on Base)
* Subscription plans: Pro $149/mo, Business $499/mo, Scale $1,999/mo, Enterprise from $4,999/mo (see [Pricing](https://orbexa.io/en/pricing/))
* Complete six-dimension scores with 77 verification signals
* All data derived from publicly verifiable, authoritative sources
* JSON response format

## 6.2 Verification Endpoint

### GET /api/otr/verify/:domain

Query the OTR trust score for a specified domain.

**Request example**:

```bash theme={null}
curl https://orbexa.io/api/otr/verify/example.com
```

**Path parameters**:

| Parameter | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `domain`  | string | Yes      | The domain to query (without protocol prefix) |

### Response Structure

The response is a JSON object containing the following top-level fields:

```json theme={null}
{
  "domain": "example.com",
  "name": "Example Store",
  "trust_score": 75,
  "badge": "SILVER",
  "industry": "E-Commerce",
  "dimensions": {
    "V": { "score": 82, "signals": [...] },
    "S": { "score": 68, "signals": [...] },
    "G": { "score": 70, "signals": [...] },
    "T": { "score": 65, "signals": [...] },
    "D": { "score": 72, "signals": [...] },
    "F": { "score": null, "status": "cold_mode" }
  },
  "entity_data": {
    "gleif": { ... },
    "wikidata": { ... },
    "stock": { ... }
  },
  "agent_commerce": {
    "llms_txt": true,
    "agent_json": false,
    "schema_org_product": true,
    "sitemap": true
  },
  "scanned_at": "2026-04-10T12:00:00Z",
  "otr_id": "OTR-xxxx"
}
```

### Response Field Reference

| Field            | Type   | Description                                      |
| ---------------- | ------ | ------------------------------------------------ |
| `domain`         | string | The queried domain                               |
| `name`           | string | Merchant name (brand name takes priority)        |
| `trust_score`    | number | Composite trust score from 0 to 100              |
| `badge`          | string | PLATINUM / GOLD / SILVER / BRONZE / UNRATED      |
| `industry`       | string | Industry classification                          |
| `dimensions`     | object | Scores and signal details for all six dimensions |
| `entity_data`    | object | Third-party verified entity information          |
| `agent_commerce` | object | AI agent commerce capability declarations        |
| `scanned_at`     | string | Timestamp of the most recent scan (ISO 8601)     |
| `otr_id`         | string | Unique OTR identifier                            |

### Dimension Signal Structure

Each dimension contains a `signals` array with all signals for that dimension:

```json theme={null}
{
  "signal_name": "dnssec",
  "status": "detected",
  "value": true,
  "evidence": "DNSSEC is enabled with RRSIG records",
  "source_url": "dns://example.com"
}
```

| Field         | Type   | Description                                          |
| ------------- | ------ | ---------------------------------------------------- |
| `signal_name` | string | Signal identifier                                    |
| `status`      | string | detected / not\_found / not\_scanned / fetch\_failed |
| `value`       | any    | Signal value (boolean, string, or number)            |
| `evidence`    | string | Human-readable evidence description                  |
| `source_url`  | string | Verifiable data source link                          |

## 6.3 Well-Known Endpoint

OTR also provides a standard `.well-known` endpoint that conforms to the Web service discovery specification:

### GET /.well-known/otr/verify/:domain

Returns the same data structure as the primary API, following the `.well-known` URI specification (RFC 8615).

```bash theme={null}
curl https://orbexa.io/.well-known/otr/verify/example.com
```

## 6.4 Rate Limiting

### API Query Limits

| Endpoint      | Limit                                       | Window     |
| ------------- | ------------------------------------------- | ---------- |
| API endpoints | 60 requests                                 | Per minute |
| Batch queries | Recommended 1-second interval between calls |            |

When rate limits are exceeded, the API returns HTTP 429 with a `Retry-After` header. Implement exponential backoff for automated integrations.

### Scan Request Limits

Submitting a new OTR scan request (via the scan submission form) is subject to stricter limits:

| Scope      | Limit        | Window                 |
| ---------- | ------------ | ---------------------- |
| Per domain | 3 requests   | Rolling 7-day window   |
| Per email  | 10 requests  | Rolling 24-hour window |
| Global     | 100 requests | Per day                |

* Exceeding the domain limit returns: "This domain has been submitted too many times. Please try again next week."
* Exceeding the email limit returns: "Too many requests from this email. Please try again tomorrow."
* If a scan does not complete within 2 hours, it is automatically marked as failed.

### Common Scan Errors

| Error Code            | HTTP | When It Occurs                                               |
| --------------------- | ---- | ------------------------------------------------------------ |
| `SCAN_IN_PROGRESS`    | 409  | Another scan is already running for this domain              |
| `DOMAIN_NOT_FOUND`    | 404  | Domain has not been scanned yet, submit a scan request first |
| `RATE_LIMIT_EXCEEDED` | 429  | Scan submission limits exceeded                              |

## 6.5 Integration Examples

### JavaScript / Node.js

```javascript theme={null}
async function checkTrust(domain) {
  const response = await fetch(
    `https://orbexa.io/api/otr/verify/${encodeURIComponent(domain)}`
  );
  const data = await response.json();

  console.log(`Domain: ${data.domain}`);
  console.log(`Trust Score: ${data.trust_score}`);
  console.log(`Badge: ${data.badge}`);
  console.log(`V Dimension: ${data.dimensions.V.score}`);
  console.log(`S Dimension: ${data.dimensions.S.score}`);

  return data;
}

// Usage
checkTrust('example.com');
```

### Python

```python theme={null}
import requests

def check_trust(domain: str) -> dict:
    url = f"https://orbexa.io/api/otr/verify/{domain}"
    response = requests.get(url)
    data = response.json()

    print(f"Domain: {data['domain']}")
    print(f"Trust Score: {data['trust_score']}")
    print(f"Badge: {data['badge']}")

    return data

# Usage
check_trust("example.com")
```

### cURL

```bash theme={null}
# Query and pretty-print the output
curl -s https://orbexa.io/api/otr/verify/example.com | jq .

# Extract only the trust score and badge
curl -s https://orbexa.io/api/otr/verify/example.com | jq '.trust_score, .badge'
```

## 6.6 Querying with AI Agents

You can ask AI assistants such as ChatGPT or Claude to query and analyze trust scores on your behalf. Example prompt:

```
Please query the OTR trust score for example.com.
Access https://orbexa.io/api/otr/verify/example.com,
then analyze each dimension's score, tell me which areas
need the most improvement, and provide specific action steps.
```

The AI agent will automatically call the API, parse the results, and deliver personalized optimization recommendations. This is what "bring your own AI" means — you do not need to install any ORBEXA product, just an internet-connected AI assistant.

## 6.7 Self-Hosted Trust Assessment

If you want to build your own trust assessment system (for example, to evaluate only your own supply chain), the core logic of the OTR protocol is open-source:

* **OTR Protocol Specification**: [github.com/yb48666-ctrl/OTR-Protocol-by-orbexa](https://github.com/yb48666-ctrl/OTR-Protocol-by-orbexa)
* **All data sources are public**: GLEIF, Wikidata, Finnhub, SEC EDGAR, DNS records, SSL certificates, and more
* **You can customize weights and signals to fit your requirements**

ORBEXA provides a production-ready implementation, but the protocol itself is open. Anyone can build their own trust assessment system based on the same principles.

***

**Next chapter**: [MCP Server — Trust Query Tool](/en/book-2/ch7-mcp-server) — Enable AI agents to invoke OTR trust queries directly via the MCP protocol