# Amalgix — Complete API Reference

> Evidence-backed financial filing and contract intelligence for AI agents.
> Pay-per-request with USDC via x402 protocol. No subscriptions or prepaid credits.
> Wallet login and API keys identify dashboard/API usage; paid execution still uses x402.

## Free Endpoints (no payment required)

- GET /               — Landing page
- GET /dashboard      — Wallet dashboard
- GET /health         — Service health: uptime status
- GET /llms.txt       — Concise AI discovery (this format)
- GET /llms-full.txt  — Complete API reference (this file)
- GET /openapi.json   — OpenAPI 3.1.0 specification
- POST /mcp           — MCP endpoint (tools/list, initialize, ping — free)
- POST /api/v1/auth/evm/nonce   — Create wallet-login nonce
- POST /api/v1/auth/evm/verify  — Verify signed wallet login message
- GET /api/v1/me                — Current wallet/API key identity
- POST /api/v1/api-keys         — Create API key after wallet login
- GET /api/v1/jobs              — Recent analysis jobs after wallet login
- GET /api/v1/requests          — Recent request logs after wallet login
- GET /api/v1/payments          — Recent x402 payment events after wallet login

────────────────────────────────────────────────

## Public Paid REST Workflows

- POST /api/v1/filings/analyze — Financial Filing Intelligence
- POST /api/v1/contracts/review — Contract Risk Intelligence
- POST /api/v1/analyze — General evidence analysis compatibility endpoint

Legacy REST utility endpoints for extraction, summarization, and translation are disabled by default. They can be re-enabled by the operator with AMALGIX_ENABLE_LEGACY_REST_TOOLS=true, but they are not public products.

## MCP Tools — POST /mcp (JSON-RPC 2.0)

MCP exposes the core paid workflows plus compatibility utilities through a single endpoint.
Transport: Streamable HTTP (POST /mcp with Content-Type: application/json)

### analyze_public_filing — Financial Filing Intelligence
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| ticker | string | Conditional | Ticker symbol for SEC lookup, e.g. AAPL. Required unless content, filingUrl, or cik is provided |
| cik | string | Conditional | SEC CIK alternative to ticker |
| form | string | No | 10-K, 10-Q, or 20-F. Default: 10-K |
| year | integer | No | Filing/report year. Omit for latest matching filing |
| filingUrl | string | Conditional | Public filing/report URL |
| content | string | Conditional | Uploaded or preprocessed filing text |
| depth | string | No | quick, standard, or deep |
| question | string | No | Optional focus question |
Price: $0.03–$79.00 ceiling (dynamic, scales with document size and complexity)
Output: company, ticker, form, period, source, metrics, risk_changes, contradictions, management_tone, missing_information, evidence, confidence, not_investment_advice.
Note: Source-grounded evidence triage only; not investment advice.

### review_contract_risks — Contract Risk Intelligence
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| content | string | Conditional | Contract text or supported Base64 file content. Required unless fileUrl is provided |
| fileUrl | string | Conditional | HTTPS URL to a contract, MSA, NDA, procurement agreement, vendor agreement, or compliance document |
| contractType | string | No | nda, msa, saas, procurement, lease, employment, or other |
| jurisdiction | string | No | Jurisdiction metadata |
| depth | string | No | quick, standard, or deep |
| focus | string | No | Optional focus area |
Price: $0.03–$79.00 ceiling (dynamic, scales with document size and complexity)
Output: contract_type, parties, dates, commercial_terms, obligations, risk_flags, missing_clauses, unusual_terms, evidence, confidence, not_legal_advice.
Privacy: raw contract text is not persisted by default. STORE_CONTRACT_RESULTS=false stores metadata/hash/job status only.
Note: Evidence triage only; not legal advice.

### analyze_document — General Evidence Analysis
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| content | string | Conditional | Text or supported file content. Required unless fileUrl is provided |
| query | string | Yes | Analysis question or focus area |
| fileUrl | string | Conditional | HTTPS URL to download and analyze |
| analysisType | string | No | auto, general_evidence, financial_filing, or contract_review |
Price: $0.03–$79.00 ceiling (dynamic, scales with document size and complexity)
Output: evidenceFindings with claim, evidence, sourceRef, confidence, and verificationStatus.
Use dedicated filing or contract tools when the domain is known.

### Compatibility MCP utilities
extract_web, summarize, and delegate_bulk_translate remain available through MCP for existing integrations. They are compatibility utilities, not public REST products in the evidence-grade filing/contract positioning.

### estimate_cost — Cost Preview (FREE)
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tool | string | Yes | Tool to estimate cost for |
| content_length | integer | No | Approximate content size in characters |
| depth | string | No | quick, standard, or deep |
| input_source | string | No | content, file_url, filing_url, ticker, cik, or unknown |

### health_check — Service Status (FREE)
No parameters required.

────────────────────────────────────────────────

## Pricing Model

Dynamic pricing uses the active non-Gemini GPT/Claude/Mistral route with Opus-competitive market anchoring: micro-documents keep viable floor economics, 80KB–1MB targets 50%+ margin, and larger documents are priced below Opus 4.7 direct-call cost. Prices scale dynamically with document size and request complexity from $0.03 to a $79 hard safety cap.

| Tier | Size | Price Range | Pipeline |
|------|------|------------|----------|
| L1 Lightweight | <128KB | $0.03–$0.16 | Haiku + Mistral supplement reserve |
| L2 Standard | 128KB–1.28MB | $0.23+ | GPT-5.4 mini extraction with Haiku verification |
| L3 Enterprise | 1.28MB–20MB | Scales to $79 ceiling | Chunked GPT-5.4 mini workers with Haiku critic and Sonnet synthesis |

Use estimate_cost (FREE) for exact per-request quotes.

Payment: USDC on Base or Solana (ExactScheme, dynamic per-request pricing)
Use estimate_cost to get exact pricing before paying.

## Technical Features
- Crucible™ Engine: source-grounded analysis facade with intelligent mode routing
- Evidence Findings: claim, evidence, sourceRef, confidence, and verificationStatus
- Playbooks: general_evidence, financial_filing, and contract_review
- Knowledge Graph Grounding: Entity extraction with relationship mapping
- Schema-Enforced Output: Structured JSON with Zod validation
- XSS Sanitization: Automatic output sanitization and schema validation
- OCR/scanned-PDF support: internal document ingestion and preprocessing capability, not a standalone public endpoint
- Self-Healing: Autonomous error recovery with circuit breakers
- Rate Limiting: 60 requests/minute per IP
- Concurrency Gate: Capacity-gated paid execution (sequential by default, configurable)

## Discovery Files
- /llms.txt — Concise version
- /llms-full.txt — This file (complete reference)
- /openapi.json — OpenAPI 3.1.0 spec
- /.well-known/x402 — x402 resource list
- /.well-known/x402.json — Enriched x402 discovery
- /.well-known/mcp.json — MCP discovery
- /.well-known/mcp/server-card.json — Smithery card
- /.well-known/ai-plugin.json — AI plugin manifest
- /.well-known/agent-card.json — A2A protocol agent card
- /.well-known/agents.json — API discovery for LLM orchestrators
- /.well-known/identity.json — Official identity declaration
- /sitemap.xml — XML sitemap

## Contact
- Website: https://amalgix.io
- Email: support@amalgix.io