API Documentation
Amalgix is an MCP-native AI gateway for evidence-grade financial filing and contract intelligence. The public paid REST workflows are financial filing analysis, contract risk review, and general evidence analysis; legacy utility tools remain available through MCP for compatibility. The core analysis path is powered by Crucible™ Evidence Engine, which returns source-grounded findings with confidence and verification metadata.
Quick Start
Add Amalgix to your MCP client configuration. Wallet login is only needed for dashboard/API key management.
{
"mcpServers": {
"amalgix": {
"url": "https://amalgix.io/mcp",
"transport": "streamable-http"
}
}
}REST API
In addition to MCP, Amalgix provides a REST API for the core evidence workflows — no JSON-RPC wrapper needed. Legacy extraction, summarization, and translation utilities are MCP-compatible and are not public REST products by default.
| Endpoint | Method | Description | Price |
|---|---|---|---|
/api/v1/analyze | POST | General evidence analysis with Crucible™ | $0.03 – $79 |
/api/v1/filings/analyze | POST | Financial Filing Intelligence | $0.03 – $79 |
/api/v1/contracts/review | POST | Contract Risk Intelligence | $0.03 – $79 |
/api/v1/cost | POST | Cost estimation | FREE |
/api/v1/health | GET | Health check | FREE |
REST Example
# Paid endpoint — plain curl receives HTTP 402 with payment requirements.
# Use estimate_cost first, then an x402-capable client for paid calls.
curl -X POST https://amalgix.io/api/v1/filings/analyze \
-H "Content-Type: application/json" \
-d '{"ticker": "AAPL", "form": "10-K", "question": "Find revenue trends, risk changes, contradictions, and evidence."}'Authentication (x402)
Paid tool execution uses the x402 payment protocol. Wallet sessions and API keys identify dashboard and REST usage, but they do not bypass payment or represent prepaid credits.
- Agent connects to MCP endpoint via Streamable HTTP
- Paid tool call → Server responds HTTP 402 with payment requirements
- 402 response includes
acceptsarray with dynamic price based on document size and request complexity (USDC on Base or Solana) - Exact payment — Agent pays the computed price, dynamically scaled by document size and complexity (from $0.03 floor to $79 ceiling)
- Processing — Crucible™ Engine processes the request
- Settlement — Payment settled on-chain; you pay exactly the quoted amount
analyze_document
General evidence analysis powered by Crucible™ Evidence Engine. Returns source-grounded findings with claim, evidence, sourceRef, confidence, verificationStatus, and routing metadata.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
content | string | conditional | Full document text or supported Base64 file. Required unless fileUrl is provided. Max 20MB. |
fileUrl | string (URL) | conditional | HTTPS URL to a text-extractable source document. |
query | string | required | Analysis question or focus area. |
analysisType | string | optional | auto, general_evidence, financial_filing, or contract_review. |
format | string | optional | Force input format: auto, text, pdf, docx, xlsx, csv, html. Default: auto-detect. |
sourceType | string | optional | Source metadata: text, file_url, upload_base64, public_url, ticker. |
ticker | string | optional | Company ticker symbol for financial filing context. |
partyPerspective | string | optional | Review perspective: buyer, seller, vendor, customer, neutral. Default: neutral. |
jurisdiction | string | optional | Jurisdiction metadata for contract review context. Max 80 chars. |
Response
{
"analysis": {
"summary": "...",
"evidenceFindings": [{ "claim": "...", "evidence": "...", "sourceRef": "document:line:12", "confidence": "high", "verificationStatus": "supported" }],
"contradictions": [],
"overallConfidence": "high"
},
"meta": {
"chunksProcessed": 4,
"chunksTotal": 4,
"latencyMs": 12400,
"estimatedCost": 0.0034,
"routingTier": "large_context"
}
}analyze_public_filing
Financial Filing Intelligence for public SEC filings. Accepts content, filingUrl, ticker, or CIK for 10-K, 10-Q, and 20-F workflows. Returns metrics, risk changes, contradictions, management tone, missing information, evidence, confidence, and not_investment_advice. Not investment advice.
Parameters
| Field | 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 | optional | 10-K, 10-Q, or 20-F. Default: 10-K. |
year | integer | optional | Filing/report year. Omit for latest matching filing. |
filingUrl | string (URL) | conditional | Public filing/report URL. |
content | string | conditional | Uploaded or preprocessed filing text. |
depth | string | optional | quick, standard, or deep. |
question | string | optional | Optional focus question. |
review_contract_risks
Contract Risk Intelligence for contracts, MSAs, NDAs, procurement agreements, and compliance documents. Returns risk clauses, obligations, deadlines, liability exposure, missing terms, unusual clauses, evidence, and human-review flags. Not legal advice.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
content | string | conditional | Contract text or supported Base64 file. Required unless fileUrl is provided. |
fileUrl | string (URL) | conditional | HTTPS URL to a contract or compliance document. |
query | string | optional | Optional focus area. Default reviews payment, termination, liability, confidentiality, jurisdiction, renewal, obligations, deadlines, missing terms. |
contractType | string | optional | nda, msa, saas, procurement, lease, employment, or other. |
jurisdiction | string | optional | Jurisdiction metadata for review context. |
depth | string | optional | quick, standard, or deep. |
focus | string | optional | Optional review focus. |
format | string | optional | Force input format: auto, text, pdf, docx, xlsx, csv, html. Default: auto. |
partyPerspective | string | optional | Review perspective: buyer, seller, vendor, customer, neutral. Default: neutral. |
sourceType | string | optional | Source metadata: text, file_url, upload_base64, public_url. |
extract_web
MCP compatibility utility for extracting readable content from public web pages with native fetch. Optionally runs Crucible™ analysis on the extracted text.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
url | string (URL) | required | Target URL. Must be http/https. |
query | string | optional | If provided, runs full analysis on extracted content. |
summarize
MCP compatibility utility for fast single-pass summarization with key points. No chunking or cross-verification.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
content | string | required | Document text. Max 5MB. |
max_length | integer | optional | Max words. Range: 10–5000. Default: 500. |
delegate_bulk_translate
MCP compatibility utility that translates all string values in a JSON object to any target language while preserving structure and keys.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
json | string | required | Valid JSON string. Max 1MB. |
target_language | string | required | Target language (e.g. "es", "fr", "de"). |
source_language | string | optional | Auto-detected if omitted. |
preserve_keys | boolean | optional | Keep keys untranslated. Default: true. |
estimate_cost
Preview x402 USDC cost for any tool before making a paid call. Always free.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
tool | string | required | Tool name to estimate. |
content_length | integer | optional | Approximate character count of your input document (not bytes). |
depth | string | optional | quick, standard, or deep. Default: standard. |
input_source | string | optional | content, file_url, filing_url, ticker, cik, or unknown. |
query | string | optional | Include your analysis query for accurate pricing — high-output requests may cost more. |
content_sample | string | optional | Short content excerpt for multilingual/high-output pricing hints without sending the full document. |
workflow | string[] | optional | Multi-tool workflow for combined estimate. |
health_check
Verify service health and engine availability. Always free.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
verbose | boolean | optional | Include per-provider status. Default: false. |
estimate_cost, health_check) are documented here but intentionally excluded from /openapi.json and x402 discovery indexes. They require no payment and are always available via MCP or REST.Error Codes
| Code | Level | Description |
|---|---|---|
INPUT_TOO_LARGE | Tool | Exceeds size limit (20MB analyze, 5MB summarize, 1MB translate). |
INVALID_JSON | Tool | Input is not valid JSON (delegate_bulk_translate). |
ALL_PROVIDERS_DOWN | Tool | All LLM providers failed. Retry after 30s. |
TOO_MANY_FAILURES | Tool | 50%+ chunks failed verification. |
EMPTY_CONTENT | Tool | URL returned no extractable content. |
SSRF_BLOCKED | Tool | URL targets private/internal network. |
429 | HTTP | Rate limit exceeded (MCP: 60/min, free REST: 120/min per IP). |
413 | HTTP | Request body exceeds limit (free REST /api/v1/cost: 10KB max). |
Rate Limits & Constraints
- Rate limit: MCP 60 req/min per IP; free REST 120 req/min per IP
- Core analysis workflows: 20MB hard limit (recommended ≤10MB for optimal latency)
- MCP compatibility summarize: 5MB max
- MCP compatibility delegate_bulk_translate: 1MB max
- Concurrency: Capacity-gated paid execution (sequential by default)
- LLM timeout: 45–180s per call (scales dynamically with document size)
- x402 ceiling: $79 USDC hard safety cap; prices scale dynamically with document size and request complexity
Output Schemas
Paid analysis responses include a meta object with latencyMs (pipeline duration) and estimatedCost (internal API cost, not the x402 charge). Free tools (estimate_cost, health_check) return their own lightweight schemas. Confidence levels: high (strong source support), medium (partial support or minor discrepancies), low (limited support).