Documentation

Everything you need to use Lantern and integrate with the API.

Getting Started

Lantern is a provenance system for digital art. Artists register their work on the Base blockchain, creating a permanent, tamper proof record of ownership. Anyone can verify who created a piece using the website or browser extension.

Create an account on the Dashboard (requires an invite key)
Link your platform accounts to prove you own them
Upload and register your art
Share your Lantern ID or let the extension detect it automatically

Register Art

Registration creates a blockchain record tied to your identity.

Go to the Dashboard and sign in
Upload your image file (PNG, JPEG, WebP, GIF, or TIFF, up to 50MB)
Provide the URL where the work is posted (must match a verified platform account)
Lantern computes a SHA-256 hash and a perceptual hash of your file
The SHA-256 hash is registered on the Base blockchain with an EIP-712 signature
You receive a Lantern ID (format: LNTN-xxxxxxxx) that anyone can look up

If a visually similar image is already registered, the system will block the registration and point you to the existing record. If that record is not yours, you can file a dispute.

Verify Content

There are three ways to verify content:

By Lantern ID

Enter the ID on the Verify page or visit /verify/LNTN-xxxxxxxx directly.

By File Upload

Upload an image on the Verify page. The system first tries an exact SHA-256 match. If that fails, it computes a perceptual hash (dHash) and searches for visually similar registered works. This catches compressed, resized, or re-encoded versions.

By Extension

Right-click any image and select "Lantern" from the context menu. The extension uploads the image to the API for exact and perceptual matching, and the popup opens with the result.

Browser Extension

The Lantern extension works on Twitter/X, Pixiv, DeviantArt, ArtStation, and Instagram. It automatically detects Lantern IDs in posts and shows colored verification pins.

Features

Automatic badge detection on supported platforms
Right-click any image to verify (exact + perceptual matching)
Click a badge to see full provenance details
Auto-detect registered art on pages (optional, enable in settings)
Per-platform toggles and cache management in options

Platform Linking

Linking your platform account proves you own it. This is required before you can register content from that platform.

Go to Dashboard and click "Link a Platform"
Select the platform and enter your username and profile URL
You receive a verification code
Post the code in your bio or a public post on that platform
Submit the proof URL (link to the post or profile showing the code)
An admin reviews and verifies the link

Supported platforms: Twitter/X, Pixiv, DeviantArt, ArtStation, Instagram.

Disputes

If someone registered your work, you can file a dispute from the verification page. Provide your email, a description of your claim, and evidence URLs showing you are the original creator. An admin will review the evidence and resolve the dispute.

If a dispute is upheld, the registration is flagged and the badge changes to "Disputed" across all platforms where the extension is active.

Badge States

Verified Creator: Creator has a verified platform link matching the content source
Unverified Creator: Registration exists but creator identity is self-declared
Disputed: A dispute has been filed against this registration
Revoked: The creator or an admin revoked the registration
Chain Review Needed: The on-chain record does not match the database record

API Overview

Base URL: https://api.lantern-us.com

All responses are JSON. Authenticated endpoints require a JWT token in the Authorization: Bearer <token> header. Tokens are obtained via the login or register endpoints.

Public Endpoints

No authentication required.

GET/verify/{lantern_id}

Look up a registration by Lantern ID. Returns creator info, metadata, chain status, dispute status, and perceptual hashes if available.

GET/verify/hash/{content_hash}

Look up by SHA-256 hash. Accepts with or without sha256: prefix. Returns 400 for invalid format, 404 if not found.

POST/verify/image

Upload-based verification. Multipart image field. Tries exact SHA-256 match first, falls back to perceptual matching. Returns a DisplayBlock the extension and web app render verbatim.

GET/creator/{wallet_address}

List content registered by a wallet address. Supports offset and limit query params for pagination.

GET/config/platforms

Returns the hostname-to-platform map and display labels used by the extension to auto-detect supported sites. Cached 1h client-side.

GET/config/features

Returns feature flags (e.g. auto-scan kill-switch). Cached 1h client-side.

POST/report/{lantern_id}

Submit a report. Body: {reason, evidence_url?, reporter_email?}.

GET/health

Returns {status: 'ok'} if the API is running.

Auth Endpoints

POST/auth/register

Create account. Body: {email, password, display_name, invite_key}. Returns JWT token and user info.

POST/auth/login

GET/auth/me

Get current user info including content count, linked platforms, wallet address, and admin status. Requires auth.

POST/auth/revoke-my-tokens

Invalidate all of the current user's outstanding JWT tokens. Used by web logout so signing out actually ends every session, not just the tab. Returns 204.

Content Endpoints

All require authentication.

POST/register

Register new content. Multipart form: image file + source_platform + source_url + optional title, description, creation_tool. Requires a verified platform link. Limited to 10/day.

PATCH/{lantern_id}/backfill-hash

Add perceptual hashes to an existing registration. Upload the original file. Only the creator can backfill. Verifies SHA-256 matches.

POST/revoke/{lantern_id}

Revoke your own registration. This is permanent and triggers an on-chain revocation.

GET/stats

System stats: total images, creators, on-chain count, file type breakdown, contract address.

Similarity Search

Perceptual matching endpoints for detecting re-encoded, compressed, or resized images.

GET/verify/similar/{dhash_hex}?threshold=10

Search by 16-character hex dHash. Returns up to 5 matches within the Hamming distance threshold (0-20, default 10). Includes confidence scores and match type.

POST/verify/similar/batch

Batch search. Body: {hashes: [...], threshold: 10}. Up to 50 hashes per request. Returns matches grouped by query hash.

Match Types

perceptual_strong (distance 0 to 5): High confidence, very likely the same image
perceptual_weak (distance 6 to 10): Moderate confidence, likely the same image after significant transformation

Platform Endpoints

All require authentication.

POST/platform/link

Start platform verification. Body: {platform, platform_username, platform_url}. Returns a verification code to post publicly.

POST/platform/verify/{link_id}

Submit proof URL showing the verification code. Body: {proof_url}.

GET/platform/links

List your platform links and their status (pending, verified, rejected).

DELETE/platform/link/{link_id}

Remove a platform link.

Supported Platforms

twitter, pixiv, deviantart, artstation, instagram

Dispute Endpoints

POST/dispute/{lantern_id}

File a dispute. Body: {disputant_email, claim_description, evidence_urls, disputant_name?, evidence_notes?}. Throttled: 5/hour per IP. No auth required.

GET/dispute/{lantern_id}

List public disputes filed against a registration. No auth required.

GET/disputes/my

List disputes filed against your content. Auth required.

Rate Limits

Endpoint	Limit	Window
Public verify endpoints	60 requests	per minute per IP
Config endpoints (/config/*)	60 requests	per minute per IP
Login	5 attempts	per 15 minutes per email
Content registration	10 registrations	per day per user
Reports	10 filings	per hour per IP
Disputes	5 filings	per hour per IP