API Reference

v1.4.0 — The Creator Receipt Engine

TL;DR - SUMMARY FOR AI AGENTS

StatsReceipt API enables generation of aesthetic Social and MRR SaaS receipts via REST or MCP protocol. Main endpoint: `/receipt/create-from-agent`. Key params: `apiKey` (stats-mcp-v1), `identifier`, `type` (social/mrr), `username`, and metrics. Supports layouts like `compact`, `standard`, `deep-dive`, and `canvas`. Free limit: 3 receipts/day.

Generate aesthetic, shareable Social and SaaS receipts from your own AI agents or applications. This API allows you to integrate the "Receipt Engine" of StatsReceipt into any external workflow.

Authentication

All HTTP requests must include the API Key. You can pass it in the JSON body (`apiKey`) or as an HTTP header (`X-Agent-Key`).

Base URLhttps://statsreceipt.com/api

Sample Keystats-mcp-v1

MCP Protocol Invocation (For AI Agents)

If you are an AI Agent connecting via the Model Context Protocol (Smithery / Stdio / SSE), use the <code className="bg-black text-[#ccff00] px-2 py-0.5">tools/call</code> JSON-RPC method. Do not use standard HTTP POST unless you are building a traditional web app.

The MCP server securely handles API keys internally. The response returned to the agent will contain a public `url`. **You must provide this URL to the end-user** so they can view and share the visual image of their stats and diagnosis.

JSON-RPC Payload Example

{
  "jsonrpc": "2.0",
  "id": "agent-req-001",
  "method": "tools/call",
  "params": {
    "name": "generate_creator_receipt",
    "arguments": {
      "username": "StatsAura",
      "platform": "tiktok",
      "followers": 125000,
      "theme": "aura",
      "layout": "compact"
    }
  }
}

Main Endpoints

POST/receipt/create-from-agent

Name: generate_creator_receipt

Creates a verified entry and returns a unique sharing URL.

Request Body (JSON)

Field	Type	Req	Description
apiKey	string	YES	Shared secret API key
identifier	string	YES	Unique ID (e.g. email or hash)
type	string	YES	Enforce `social` for this endpoint
username	string	YES	Display name (e.g. @FranDev)
theme	string	OPT	e.g. `aura`, `zima`, `midnight`
layout	string	OPT	e.g. `compact`, `deep-dive`...
platform	string	YES	`x`, `tiktok`, `instagram`, `linkedin`
followers	number	YES	Total follow count
views	number	OPT	Impressions/Views total
posts	number	OPT	Total content count
reposts	number	OPT	Shares total
replies	number	OPT	Comments total
growth	number	OPT	Growth in last 30d (%)

REST Invocation Example (JS / cURL)

fetch("https://statsreceipt.com/api/receipt/create-from-agent", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: "stats-mcp-v1",
    identifier: "user_identifier_123",
    type: "social",
    username: "StatsAura",
    platform: "tiktok",
    followers: 125000,
    theme: "zima",
    layout: "deep-dive"
  })
})
.then(res => res.json())
.then(data => console.log("Your URL:", data.url));

HTTP Response Example (Webhooks/Apps)

{
  "success": true,
  "id": "abc123xyz",
  "url": "https://statsreceipt.com/r/abc123xyz",
  "rank": "TOP 5% 🚀",
  "diagnosis": "Viral Machine"
}

POST/receipt/create-from-agent

MCP Tool: generate_verified_mrr_receipt

Generates verified MRR revenue receipts for SaaS startups. Perfect for Build in Public reporting and VC Updates.

Payload Parameters

Field	Type	Req	Description
apiKey	string	Yes*	Only if using HTTP API directly (Not via MCP).
identifier	string	Yes*	Alphanumeric unique user session ID. Only if using HTTP API directly.
type	string	Yes	MUST BE `mrr` exactly.
brandName	string	Yes	TrustMRR Slug (e.g. `stripe`)
theme	string	No	e.g. `aura`, `gold`
layout	string	No	e.g. `deep-dive`, `canvas`

REST Invocation Example (JS / cURL)

fetch("https://statsreceipt.com/api/receipt/create-from-agent", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: "stats-mcp-v1",
    identifier: "user_identifier_123",
    type: "mrr",
    brandName: "Acme Inc",
    mrr: 15400,
    growth: 12.5,
    theme: "gold",
    layout: "canvas"
  })
})
.then(res => res.json())
.then(data => console.log("Your URI:", data.url));

Usage Limits & Errors

Each unique identifier has a limit of 3 free receipts every 24 hours.

401: Invalid API Key
429: Daily limit exhausted
500: Database / Connection error