Home/API Reference

API Reference

Technical documentation for integrating ValidTrust badge verification into your application.

API Status: ValidTrust currently operates as a client-side application with direct Supabase integration. A public REST API for third-party integrations is on our roadmap. This page documents the current verification endpoints and planned API features.

Badge Verification

Every badge can be verified by visiting its unique verification URL:

https://validtrust.io/verify?code={badge_code}

The verification page displays the badge status, type, message, sender's verification layers, and creation date. No authentication is required to check a badge — anyone with the link can view its status.

Badge Data Structure

Each badge contains the following data:

{
  "id": "uuid",
  "short_code": "LBxJ5RuX",
  "badge_type": "public" | "private",
  "message": "Trust me — I'm real.",
  "display_name": null | "Alice",
  "status": "pending" | "active" | "used" | "claimed" | "expired" | "refunded",
  "sender_wallet": "So1ana...WaLLet",
  "recipient_wallet": null | "Rec1p...WaLLet",
  "escrow_address": null | "EsCr0w...PDA",
  "webauthn_credential_id": "base64...",
  "email_verified": true | false,
  "email_hash": "sha256...",
  "created_at": "2026-02-11T12:00:00Z",
  "expires_at": "2026-02-13T12:00:00Z",
  "claimed_at": null | "2026-02-11T14:30:00Z",
  "tx_signature": null | "5Kz3...txSig"
}

Embeddable Badge Widget

You can embed a ValidTrust verification badge on your website. The badge shows your trust status in real-time:

<!-- Planned: Embeddable Badge Widget -->
<iframe
  src="https://validtrust.io/embed?code={badge_code}"
  width="320"
  height="80"
  frameborder="0"
  style="border-radius: 12px;"
></iframe>

Coming soon: The embeddable widget is currently in development. It will display a compact verification badge that websites, marketplaces, and forums can integrate.

Link Preview (OG Tags)

When badge verification links are shared on social platforms (X, Discord, Telegram, etc.), ValidTrust automatically generates rich link previews with dynamic Open Graph meta tags:

Title: "ValidTrust — Verified Badge"
Description: Dynamic based on badge type and message
Image: Badge type icon (purple hand for public, green hand for private)

This is powered by a Cloudflare Worker that intercepts crawler requests (Twitterbot, Discordbot, etc.) and returns appropriate meta tags, while normal users get the full verification page.

Planned Public API

A public REST API is planned for third-party integrations. This will allow external services to:

GET /api/v1/badge/{code}

Check a badge programmatically. Returns badge status, type, verification layers, and creation date. No authentication required.

GET /api/v1/wallet/{address}/badges

List all active badges for a given wallet address. Useful for marketplace integrations and reputation scoring.

POST /api/v1/badge/verify

Batch verify multiple badges at once. Returns verification status for an array of badge codes. Designed for marketplaces and platforms that need to verify multiple users.

WebSocket /api/v1/badge/{code}/live

Real-time updates on badge status changes. Subscribe to a badge code and receive instant notifications when a badge is claimed, expires, or changes status.

Rate Limits (Planned)

Tier	Requests/min	Daily Limit
Public (no key)	30	1,000
Authenticated	120	10,000
Enterprise	600	Unlimited

Browser Extension

The ValidTrust browser extension (in development) will provide:

Automatic badge verification on social media profiles
Inline trust indicators next to usernames
One-click badge creation from any webpage
Wallet integration for seamless on-chain $SOL transactions

The extension will use the same public API endpoints documented above.

SDKs & Libraries (Planned)

We plan to release official SDKs for common platforms:

JavaScript/TypeScript — npm package for Node.js and browser integration
React Component — Drop-in badge verification component
Python — Server-side verification library

Interested in API access or integration? Contact us at dev@validtrust.io