FaceMint AI — Protocol Docs

// base url

API Base

All API requests go to the FaceMint production endpoint. HTTPS is required.

https://facemint-production.up.railway.app

// authentication

Authentication

The FaceMint API is currently open during the Genesis phase. No API key is required. Rate limits apply per IP. Future versions will support API key authentication for premium integrations.

// No auth header needed during Genesis phase
fetch("https://facemint-production.up.railway.app/api/mint", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ entity: "shadow fox", mood: "stoic" })
})

// endpoints

API Reference

Core endpoints for minting, retrieving, and verifying FaceMint identities.

POST /api/mint

Mint a new permanent identity. Generates a unique pixel face, assigns a mint ID, and writes the identity to the protocol. The face is retired forever — no other entity will ever share it.

Request Body

Field	Type	Description
entity	string	Name or description of the entity (e.g. "shadow fox")
mood	string	Emotional tone for the face (e.g. "stoic", "joyful")
palette	string	Optional — color palette hint (e.g. "neon pink")
chain	string	Optional — target chain for on-chain record (default: "base")

Response (200)

{
  "mintId": "GEN-0007",
  "tier": "Genesis",
  "entity": "shadow fox",
  "palette": "deep violet with electric cyan accents",
  "mood": "stoic and watchful",
  "chain": "base",
  "mintedAt": "2026-03-04T18:22:00.000Z",
  "imageUrl": "https://...supabase.co/.../GEN-0007.png",
  "url": "https://facemintai.com/face.html?id=GEN-0007"
}

GET /api/recent

Returns the most recently minted identities, ordered by mint time. Useful for live tickers, dashboards, and protocol status pages.

Response (200)

{
  "count": 7,
  "mints": [
    {
      "mintId": "GEN-0007",
      "tier": "Genesis",
      "entity": "shadow fox",
      "palette": "deep violet with electric cyan accents",
      "mood": "stoic and watchful",
      "chain": "base",
      "mintedAt": "2026-03-04T18:22:00.000Z",
      "imageUrl": "https://...supabase.co/.../GEN-0007.png",
      "url": "https://facemintai.com/face.html?id=GEN-0007"
    }
    // ... more mints
  ]
}

GET /face/:id

Retrieve the public face page for any minted identity. Returns an HTML page with the pixel portrait, entity dossier, and verification status. Use for embeds, previews, and verification links.

Example

https://facemintai.com/face.html?id=GEN-0005

// identity schema

Identity Object

Every minted face produces an identity object with the following fields. This is the canonical schema for FaceMint identities across all integrations.

FaceMint Identity

Field	Type	Description
mintId	string	Unique identifier (e.g. GEN-0007, PRI-0311)
tier	string	Mint tier — "Genesis", "Prime", "Signal", etc.
entity	string	Name or description of the entity
palette	string	Color palette used for the portrait
mood	string	Emotional tone of the face
chain	string	Target blockchain (e.g. "base")
mintedAt	ISO 8601	Timestamp of when the identity was minted
imageUrl	URL	Direct link to the pixel portrait image
url	URL	Public face page URL for verification

// integration guide

3-Step Integration

Give your AI agent, bot, or app a permanent verifiable identity in three steps.

01 — Mint a Face

POST /api/mint
{
  "entity": "your agent name",
  "mood": "determined",
  "palette": "midnight blue"
}

02 — Embed the ID

Store the returned mintId in your agent's profile, bio, or metadata. This is your agent's permanent, verifiable identity anchor.

My identity is GEN-0007
Verify me → https://facemintai.com/face.html?id=GEN-0007

03 — Verify Anywhere

Anyone can verify an identity by fetching the face page or calling the API. The pixel portrait, entity dossier, and mint timestamp provide cryptographic-grade proof of identity.

GET /face/GEN-0007
// Returns full identity page with portrait & dossier

// error handling

Error Responses

The API returns standard HTTP status codes. Errors include a JSON body with a message field.

Error Codes

Code	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Missing or invalid parameters
404	Not Found	Mint ID does not exist
429	Rate Limited	Too many requests — slow down
500	Server Error	Internal error — retry or contact support

// Example error response
{
  "error": true,
  "message": "Entity description is required",
  "code": 400
}

Protocol Documentation