{ "openapi": "3.1.0", "info": { "title": "DJD Agent Score API", "description": "Wallet screening for paid agent workflows on Base. Start with score lookups before payout or paid route execution, then add history, forensics, monitoring, and alerts when the workflow needs more depth. Paid endpoints accept x402 on Base or API key access for monthly plans.", "version": "2.0.0", "contact": { "email": "feedback@djdagentscore.dev" }, "license": { "name": "MIT", "url": "https://github.com/jacobsd32-cpu/djdagentscore/blob/main/LICENSE" } }, "servers": [ { "description": "Production", "url": "https://djdagentscore.dev" } ], "tags": [ { "name": "score", "description": "Core screening lookups and score computation" }, { "name": "history", "description": "Historical score data and trend views (paid)" }, { "name": "forensics", "description": "Wallet investigation summaries and incident timelines (paid)" }, { "name": "monitoring", "description": "Managed score and forensics monitoring subscriptions" }, { "name": "webhooks", "description": "Webhook subscriptions for watched wallets" }, { "name": "data", "description": "Deeper context endpoints like economy, graph, ratings, and blacklist reads" }, { "name": "register", "description": "Optional wallet profile metadata and identity context" }, { "name": "report", "description": "Fraud reporting" }, { "name": "certification", "description": "Optional certification endpoints" }, { "name": "system", "description": "Health, docs, and metadata" }, { "name": "api-keys", "description": "API key management (admin)" } ], "paths": { "/v1/score/basic": { "get": { "tags": [ "score" ], "summary": "Basic score lookup", "description": "Returns composite score, tier, confidence, recommendation, and model version. Free tier: 10 requests/day per IP. No payment required.", "operationId": "getBasicScore", "parameters": [ { "$ref": "#/components/parameters/wallet" } ], "responses": { "200": { "description": "Score returned (may include stale:true if RPC was unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicScoreResponse" }, "example": { "wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528", "score": 13, "tier": "Unverified", "confidence": 0.1, "recommendation": "insufficient_history", "modelVersion": "1.0.0", "lastUpdated": "2026-02-21T20:00:00.000Z", "computedAt": "2026-02-21T20:00:00.000Z", "scoreFreshness": 0.85 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/FreeTierExhausted" } } } }, "/v1/score/full": { "get": { "tags": [ "score" ], "summary": "Full score with dimension breakdown", "description": "Returns the composite score plus all four dimension scores (reliability, viability, identity, capability), integrity flags, data availability assessment, and improvement path. **Requires x402 payment of $0.10 USDC on Base.**", "operationId": "getFullScore", "parameters": [ { "$ref": "#/components/parameters/wallet" } ], "security": [ { "x402": [] } ], "x-x402": { "price": "$0.10", "network": "base" }, "responses": { "200": { "description": "Full score returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullScoreResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/score/refresh": { "post": { "tags": [ "score" ], "summary": "Force live recalculation", "description": "Bypasses the cache and triggers a fresh on-chain scan. Returns the full score response. **Requires x402 payment of $0.25 USDC on Base.** Prefer POST; GET is accepted for backward compatibility but deprecated.", "operationId": "refreshScore", "parameters": [ { "$ref": "#/components/parameters/wallet" } ], "security": [ { "x402": [] } ], "x-x402": { "price": "$0.25", "network": "base" }, "responses": { "200": { "description": "Freshly computed full score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullScoreResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "score" ], "summary": "Force live recalculation (deprecated — use POST)", "description": "**Deprecated.** Use `POST /v1/score/refresh` instead. This GET alias is kept for backward compatibility only.", "operationId": "refreshScoreDeprecated", "deprecated": true, "parameters": [ { "$ref": "#/components/parameters/wallet" } ], "security": [ { "x402": [] } ], "x-x402": { "price": "$0.25", "network": "base" }, "responses": { "200": { "description": "Freshly computed full score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullScoreResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/score/compute": { "post": { "tags": [ "score" ], "summary": "Queue async score computation", "description": "Submits a background full-scan scoring job and returns a `jobId` immediately (HTTP 202). Use `GET /v1/score/job/{jobId}` to poll for completion. Free — no payment required. Useful when the caller cannot wait 20-150s for the synchronous endpoints.", "operationId": "computeScore", "parameters": [ { "name": "wallet", "in": "query", "required": false, "description": "Wallet address (deprecated — prefer JSON body)", "deprecated": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "requestBody": { "description": "Preferred: pass wallet in JSON body", "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Base wallet address" } } }, "example": { "wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528" } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] }, "wallet": { "type": "string" }, "pollUrl": { "type": "string", "description": "Relative URL to poll for job status" } } }, "example": { "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "pending", "wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528", "pollUrl": "/v1/score/job/a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/score/job/{jobId}": { "get": { "tags": [ "score" ], "summary": "Poll async scoring job", "description": "Returns the current status of a scoring job submitted via `POST /v1/score/compute`. Jobs expire after 10 minutes.", "operationId": "getJobStatus", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status (pending, complete, or error)", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "complete", "error" ] }, "wallet": { "type": "string" }, "result": { "$ref": "#/components/schemas/FullScoreResponse", "description": "Present when status=complete" }, "error": { "type": "string", "description": "Present when status=error" } } } } } }, "404": { "description": "Job not found or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agent/register": { "post": { "tags": [ "register" ], "summary": "Register an agent wallet", "description": "Voluntarily attach optional public metadata to a wallet. This feeds the Identity dimension and linked profile surfaces. GitHub URL is asynchronously verified against the GitHub API. Free — no payment required.", "operationId": "registerAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterBody" }, "example": { "wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528", "name": "DJD Score API", "description": "Reputation scoring for AI agents", "github_url": "https://github.com/owner/repo", "website_url": "https://djdagentscore.dev" } } } }, "responses": { "200": { "description": "Updated existing registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "201": { "description": "First-time registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "get": { "tags": [ "register" ], "summary": "Look up agent registration", "description": "Returns registration metadata for a wallet. Free — no payment required.", "operationId": "getRegistration", "parameters": [ { "$ref": "#/components/parameters/wallet" } ], "responses": { "200": { "description": "Registration found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Wallet not registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/report": { "post": { "tags": [ "report" ], "summary": "Submit a fraud report", "description": "Submit a fraud or misconduct report against a wallet. Verified reports reduce the target wallet's composite score by up to 25 points. **Requires x402 payment of $0.02 USDC on Base.**", "operationId": "submitReport", "security": [ { "x402": [] } ], "x-x402": { "price": "$0.02", "network": "base" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target", "reporter", "reason", "details" ], "properties": { "target": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Wallet being reported" }, "reporter": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Wallet submitting the report (must differ from target)" }, "reason": { "type": "string", "enum": [ "failed_delivery", "payment_fraud", "impersonation", "malicious_behavior", "other" ], "description": "Category of misconduct" }, "details": { "type": "string", "maxLength": 1000, "description": "Supporting details and evidence (required, max 1000 chars)" } } } } } }, "responses": { "201": { "description": "Report submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/rate": { "post": { "tags": [ "ratings" ], "summary": "Submit a mutual counterparty rating", "description": "Submit a transaction-backed 1-5 star rating for a counterparty wallet. The payer wallet becomes the rater, and the `tx_hash` must reference an indexed transaction between the two wallets. **Requires x402 payment of $0.01 USDC on Base.**", "operationId": "submitRating", "security": [ { "x402": [] } ], "x-x402": { "price": "$0.01", "network": "base" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatingRequest" } } } }, "responses": { "201": { "description": "Rating submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "description": "Duplicate rating", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data/fraud/blacklist": { "get": { "tags": [ "data" ], "summary": "Fraud report check", "description": "Check whether a wallet has active fraud reports filed against it. Returns the count and most recent reports. **Requires x402 payment of $0.05 USDC on Base.**", "operationId": "getBlacklist", "parameters": [ { "$ref": "#/components/parameters/wallet" } ], "security": [ { "x402": [] } ], "x-x402": { "price": "$0.05", "network": "base" }, "responses": { "200": { "description": "Blacklist status returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlacklistResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data/decay": { "get": { "tags": [ "data" ], "summary": "Score decay curve", "description": "Returns the historical score decay curve for a wallet using hourly score snapshots, plus trend and trajectory analysis. **Requires x402 payment of $0.15 USDC on Base.**", "operationId": "getScoreDecay", "parameters": [ { "$ref": "#/components/parameters/wallet" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum decay points to return (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "description": "Inclusive ISO 8601 lower bound for `recorded_at`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "before", "in": "query", "required": false, "description": "Inclusive ISO 8601 upper bound for `recorded_at`.", "schema": { "type": "string", "format": "date-time" } } ], "security": [ { "x402": [] } ], "x-x402": { "price": "$0.15", "network": "base" }, "responses": { "200": { "description": "Score decay data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataDecayResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data/graph": { "get": { "tags": [ "data" ], "summary": "Relationship graph", "description": "Returns directional relationship-graph intelligence for a wallet, including top counterparties and aggregate flow totals. **Requires x402 payment of $0.20 USDC on Base.**", "operationId": "getRelationshipGraph", "parameters": [ { "$ref": "#/components/parameters/wallet" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum counterparties to return (default: 25, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "security": [ { "x402": [] } ], "x-x402": { "price": "$0.20", "network": "base" }, "responses": { "200": { "description": "Relationship graph data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataGraphResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/data/ratings": { "get": { "tags": [ "data" ], "summary": "Counterparty ratings", "description": "Returns aggregate mutual-rating sentiment and recent transaction-backed ratings for a wallet. **Requires x402 payment of $0.10 USDC on Base.**", "operationId": "getRatings", "parameters": [ { "$ref": "#/components/parameters/wallet" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum ratings to return (default: 25, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "security": [ { "x402": [] } ], "x-x402": { "price": "$0.10", "network": "base" }, "responses": { "200": { "description": "Ratings data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRatingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leaderboard": { "get": { "tags": [ "data" ], "summary": "Leaderboard", "description": "Returns the top 50 wallets by current composite score. Treat this as a public score sample, not as proof of customer adoption or service quality. Free — no payment required.", "operationId": "getLeaderboard", "responses": { "200": { "description": "Leaderboard returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardResponse" } } } } } } }, "/v1/badge/{wallet}.svg": { "get": { "tags": [ "data" ], "summary": "SVG score badge", "description": "Returns an embeddable SVG badge showing the wallet's current score and tier. Cached for 10 minutes. Free — no payment required.", "operationId": "getBadge", "parameters": [ { "name": "wallet", "in": "path", "required": true, "description": "Full 40-character hex wallet address (without .svg extension)", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "responses": { "200": { "description": "SVG badge image", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/health": { "get": { "tags": [ "system" ], "summary": "Health check", "description": "Returns system status, database statistics, indexer state, and background job stats.", "operationId": "getHealth", "responses": { "200": { "description": "System healthy" } } } }, "/docs": { "get": { "tags": [ "system" ], "summary": "Interactive API documentation", "description": "Serves a Swagger UI interface for exploring and testing the API interactively. Free — no payment required.", "operationId": "getDocs", "responses": { "200": { "description": "Swagger UI HTML page", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/data/economy": { "get": { "tags": [ "data" ], "summary": "Ecosystem economy metrics", "description": "Returns aggregated ecosystem health metrics: unique wallets scored, total queries, revenue, average scores, and more. Free — no payment required.", "operationId": "getEconomyMetrics", "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Aggregation period (default: daily)", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of periods to return (max 90, default 30)", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Economy metrics returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string" }, "count": { "type": "integer" }, "metrics": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/score/batch": { "post": { "tags": [ "score" ], "summary": "Batch score lookup", "description": "Score up to 20 wallets in a single request. Returns basic score data for each wallet. **Requires x402 payment of $0.50 USDC on Base.**", "operationId": "batchScore", "security": [ { "x402": [] } ], "x-x402": { "price": "$0.50", "network": "base" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallets" ], "properties": { "wallets": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "minItems": 2, "maxItems": 20, "description": "Array of wallet addresses to score" } } }, "example": { "wallets": [ "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528", "0x1234567890123456789012345678901234567890" ] } } } }, "responses": { "200": { "description": "Batch scores returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BasicScoreResponse" } }, "count": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/metrics": { "get": { "tags": [ "system" ], "summary": "Prometheus metrics", "description": "Returns Prometheus-compatible metrics in text exposition format. Includes HTTP request counters, database gauges, and process metrics. Free — no payment required.", "operationId": "getMetrics", "responses": { "200": { "description": "Prometheus text metrics", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/admin/api-keys": { "post": { "tags": [ "api-keys" ], "summary": "Create an API key", "description": "Creates a new API key for a wallet. The raw key is returned only once on creation — store it securely. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "createApiKey", "security": [ { "adminKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Wallet address to associate with the key" }, "name": { "type": "string", "nullable": true, "description": "Optional human-readable name for the key" }, "tier": { "type": "string", "enum": [ "standard", "premium" ], "default": "standard", "description": "API key tier" }, "monthly_limit": { "type": "integer", "default": 10000, "description": "Monthly request limit" } } }, "example": { "wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528", "name": "Production key", "tier": "standard", "monthly_limit": 10000 } } } }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "api-keys" ], "summary": "List all API keys", "description": "Returns all API keys with usage stats. Raw keys are never returned — only prefixes. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "listApiKeys", "security": [ { "adminKey": [] } ], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyListItem" } }, "count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/admin/api-keys/{id}": { "delete": { "tags": [ "api-keys" ], "summary": "Revoke an API key", "description": "Soft-deletes an API key by marking it as revoked. The key will no longer authenticate requests. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "revokeApiKey", "security": [ { "adminKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "API key revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "API key revoked" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "API key not found or already revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/webhooks": { "post": { "tags": [ "webhooks" ], "summary": "Create webhook (admin)", "description": "Registers a new wallet-scoped webhook subscription. Provide either `events`, `preset`, or `presets`. If `score.threshold` is selected without an explicit `threshold_score`, the service defaults to 60. Use `forensics_filter` to restrict DJD Forensics alerts by minimum resulting risk level and/or report reasons. Managed presets also include anomaly-driven monitoring for score drops, balance freefalls, and new Sybil flags. The webhook secret is returned only once, so store it securely to verify signatures. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "createAdminWebhook", "security": [ { "adminKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet", "url" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Wallet to monitor" }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint to receive webhook payloads" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "score.updated", "score.expired", "fraud.reported", "fraud.disputed", "fraud.dispute.resolved", "forensics.risk.changed", "forensics.watchlist.entered", "forensics.watchlist.cleared", "anomaly.score_drop", "anomaly.score_spike", "anomaly.balance_freefall", "anomaly.sybil_flagged", "agent.registered", "score.threshold" ] }, "minItems": 1, "description": "Explicit events to subscribe to. May be combined with presets." }, "preset": { "type": "string", "enum": [ "score_monitoring", "forensics_monitoring", "forensics_disputes", "forensics_watchlist", "anomaly_monitoring" ], "description": "Optional preset that expands to a managed event set" }, "presets": { "type": "array", "items": { "type": "string", "enum": [ "score_monitoring", "forensics_monitoring", "forensics_disputes", "forensics_watchlist", "anomaly_monitoring" ] }, "minItems": 1, "description": "Optional preset bundle list. May be combined with explicit events." }, "threshold_score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Optional threshold for `score.threshold` alerts. Defaults to 60 when omitted." }, "forensics_filter": { "$ref": "#/components/schemas/WebhookForensicsFilter" }, "tier": { "type": "string", "enum": [ "basic", "premium" ], "default": "basic", "description": "Webhook tier" } } }, "example": { "wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528", "url": "https://example.com/webhooks/djd", "preset": "forensics_monitoring", "forensics_filter": { "minimum_risk_level": "elevated", "reasons": [ "payment_fraud" ] }, "tier": "basic" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "webhooks" ], "summary": "List webhooks (admin)", "description": "Returns all registered webhooks with delivery stats. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "listAdminWebhooks", "security": [ { "adminKey": [] } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookListItem" } }, "count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/admin/webhooks/{id}": { "get": { "tags": [ "webhooks" ], "summary": "Get webhook detail (admin)", "description": "Returns one webhook plus recent delivery attempts. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "getAdminWebhook", "security": [ { "adminKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "webhooks" ], "summary": "Delete webhook (admin)", "description": "Deactivates a webhook subscription. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "deleteAdminWebhook", "security": [ { "adminKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook deactivated" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Webhook not found or already disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/webhooks/{id}/test": { "post": { "tags": [ "webhooks" ], "summary": "Test webhook (admin)", "description": "Sends a test event payload to the webhook endpoint to verify connectivity. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "testAdminWebhook", "security": [ { "adminKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Test delivery result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the test delivery returned a 2xx status" }, "status_code": { "type": "integer", "nullable": true, "description": "HTTP status code from the webhook endpoint" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/presets": { "get": { "tags": [ "webhooks" ], "summary": "List webhook presets", "description": "Returns the preset catalog for managed score and DJD Forensics monitoring bundles.", "operationId": "listWebhookPresets", "responses": { "200": { "description": "Available webhook presets", "content": { "application/json": { "schema": { "type": "object", "properties": { "presets": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookPreset" } }, "count": { "type": "integer" } } } } } } } } }, "/v1/webhooks": { "post": { "tags": [ "webhooks" ], "summary": "Create public webhook", "description": "Self-service wallet-scoped webhook registration for API key holders. Provide either `events`, `preset`, or `presets`. If `score.threshold` is selected without an explicit `threshold_score`, the service defaults to 60. Use `forensics_filter` to restrict DJD Forensics alerts by minimum resulting risk level and/or report reasons. Managed presets also include anomaly-driven monitoring for score drops, balance freefalls, and new Sybil flags. Limited to 10 active webhooks per wallet. **Requires Bearer API key authentication.**", "operationId": "createPublicWebhook", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint to receive webhook payloads" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "score.updated", "score.expired", "fraud.reported", "fraud.disputed", "fraud.dispute.resolved", "forensics.risk.changed", "forensics.watchlist.entered", "forensics.watchlist.cleared", "anomaly.score_drop", "anomaly.score_spike", "anomaly.balance_freefall", "anomaly.sybil_flagged", "agent.registered", "score.threshold" ] }, "minItems": 1, "description": "Explicit events to subscribe to. May be combined with presets." }, "preset": { "type": "string", "enum": [ "score_monitoring", "forensics_monitoring", "forensics_disputes", "forensics_watchlist", "anomaly_monitoring" ], "description": "Optional preset that expands to a managed event set" }, "presets": { "type": "array", "items": { "type": "string", "enum": [ "score_monitoring", "forensics_monitoring", "forensics_disputes", "forensics_watchlist", "anomaly_monitoring" ] }, "minItems": 1, "description": "Optional preset bundle list. May be combined with explicit events." }, "threshold_score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Optional threshold for `score.threshold` alerts. Defaults to 60 when omitted." }, "forensics_filter": { "$ref": "#/components/schemas/WebhookForensicsFilter" } } }, "example": { "url": "https://example.com/webhooks/djd", "preset": "forensics_monitoring", "forensics_filter": { "minimum_risk_level": "watch", "reasons": [ "payment_fraud", "impersonation" ] } } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWebhookCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Maximum webhooks per wallet exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "webhooks" ], "summary": "List public webhooks", "description": "Lists all webhooks belonging to the authenticated wallet. **Requires Bearer API key authentication.**", "operationId": "listPublicWebhooks", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "Webhook list for the authenticated wallet", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/PublicWebhookListItem" } }, "count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/webhooks/{id}": { "delete": { "tags": [ "webhooks" ], "summary": "Delete public webhook", "description": "Deactivates one webhook belonging to the authenticated wallet. **Requires Bearer API key authentication.**", "operationId": "deletePublicWebhook", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Webhook not found or already disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/monitor/presets": { "get": { "tags": [ "monitoring" ], "summary": "List monitoring policy presets", "description": "Returns the managed score and DJD Forensics monitoring policies available for `/v1/monitor` subscriptions.", "operationId": "listMonitoringPresets", "responses": { "200": { "description": "Available monitoring policy presets", "content": { "application/json": { "schema": { "type": "object", "properties": { "presets": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringPreset" } }, "count": { "type": "integer" } } } } } } } } }, "/v1/monitor": { "post": { "tags": [ "monitoring" ], "summary": "Create monitoring subscription", "description": "Creates a managed monitoring subscription for a target wallet and provisions the underlying webhook delivery automatically. Policies can target any wallet; delivery is sent to your HTTPS endpoint. `score_monitoring` supports `threshold_score`. Forensics policies support `forensics_filter`. `anomaly_monitoring` delivers score-drop, score-spike, balance-freefall, and sybil-flag alerts. **Requires Bearer API key authentication.**", "operationId": "createMonitoringSubscription", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "policy_type" ], "properties": { "target_wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Wallet to monitor. Defaults to the authenticated wallet when omitted." }, "policy_type": { "type": "string", "enum": [ "score_monitoring", "forensics_monitoring", "forensics_disputes", "forensics_watchlist", "anomaly_monitoring" ], "description": "Managed monitoring policy to provision." }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint to receive monitoring webhook deliveries." }, "threshold_score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Optional score threshold for `score_monitoring`. Defaults to 60 when omitted." }, "forensics_filter": { "$ref": "#/components/schemas/WebhookForensicsFilter" } } }, "example": { "target_wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528", "policy_type": "forensics_monitoring", "url": "https://example.com/monitoring/djd", "forensics_filter": { "minimum_risk_level": "elevated", "reasons": [ "payment_fraud" ] } } } } }, "responses": { "201": { "description": "Monitoring subscription created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringSubscriptionCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Maximum monitoring subscriptions per subscriber exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "monitoring" ], "summary": "List monitoring subscriptions", "description": "Lists all managed monitoring subscriptions owned by the authenticated API-key subscriber. **Requires Bearer API key authentication.**", "operationId": "listMonitoringSubscriptions", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "Monitoring subscription list", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringSubscription" } }, "count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/monitor/{id}": { "delete": { "tags": [ "monitoring" ], "summary": "Delete monitoring subscription", "description": "Deactivates a managed monitoring subscription and its underlying webhook delivery configuration. **Requires Bearer API key authentication.**", "operationId": "deleteMonitoringSubscription", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Monitoring subscription ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Monitoring subscription deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Monitoring subscription not found or already disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/score/history": { "get": { "tags": [ "history" ], "summary": "Historical score data", "description": "Returns paginated score history with trend analysis for a wallet. Supports date-range filtering and configurable result limits. **Requires x402 payment of $0.15 USDC on Base or Bearer API key.**", "operationId": "getScoreHistory", "security": [ { "x402": [] }, { "bearerApiKey": [] } ], "x-x402": { "price": "$0.15", "network": "base" }, "parameters": [ { "$ref": "#/components/parameters/wallet" }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1-100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "description": "Return records after this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "before", "in": "query", "required": false, "description": "Return records before this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Score history returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "description": "No score history found for this wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forensics/summary": { "get": { "tags": [ "forensics" ], "summary": "DJD Forensics overview", "description": "Returns a wallet-level forensics summary: active fraud report counts, total penalties, reporter breadth, dispute status, and the most recent incidents. **Requires x402 payment of $0.10 USDC on Base or Bearer API key.**", "operationId": "getForensicsOverview", "security": [ { "x402": [] }, { "bearerApiKey": [] } ], "x-x402": { "price": "$0.10", "network": "base" }, "parameters": [ { "$ref": "#/components/parameters/wallet" } ], "responses": { "200": { "description": "Forensics overview returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForensicsOverviewResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/forensics/dispute": { "post": { "tags": [ "forensics" ], "summary": "Open a fraud-report dispute", "description": "Allows the reported wallet to open a dispute against a specific fraud report. The disputing wallet is derived from the x402 payment or API key identity and must match the report target wallet. **Requires x402 payment of $0.05 USDC on Base or Bearer API key.**", "operationId": "createForensicsDispute", "security": [ { "x402": [] }, { "bearerApiKey": [] } ], "x-x402": { "price": "$0.05", "network": "base" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudDisputeRequest" } } } }, "responses": { "201": { "description": "Fraud dispute opened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudDisputeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "description": "Fraud report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Dispute already exists or wallet is not authorized to dispute this report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/forensics/feed": { "get": { "tags": [ "forensics" ], "summary": "DJD Forensics incident feed", "description": "Returns recent fraud-report incidents across the corpus. Supports reason and date-range filtering plus configurable result limits. **Requires x402 payment of $0.30 USDC on Base or Bearer API key.**", "operationId": "getForensicsFeed", "security": [ { "x402": [] }, { "bearerApiKey": [] } ], "x-x402": { "price": "$0.30", "network": "base" }, "parameters": [ { "name": "reason", "in": "query", "required": false, "description": "Optional report reason filter", "schema": { "type": "string", "enum": [ "failed_delivery", "payment_fraud", "impersonation", "malicious_behavior", "other" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of incidents to return (1-100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "description": "Return incidents after this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "before", "in": "query", "required": false, "description": "Return incidents before this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Forensics incident feed returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForensicsFeedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/forensics/watchlist": { "get": { "tags": [ "forensics" ], "summary": "DJD Forensics watchlist", "description": "Returns a ranked watchlist of the most-reported wallets across the corpus. Supports date-range filtering and configurable result limits. **Requires x402 payment of $0.25 USDC on Base or Bearer API key.**", "operationId": "getForensicsWatchlist", "security": [ { "x402": [] }, { "bearerApiKey": [] } ], "x-x402": { "price": "$0.25", "network": "base" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of wallets to return (1-100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "description": "Return incidents after this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "before", "in": "query", "required": false, "description": "Return incidents before this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Forensics watchlist returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForensicsWatchlistResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/forensics/reports": { "get": { "tags": [ "forensics" ], "summary": "DJD Forensics incident feed", "description": "Returns fraud-report incidents for a wallet with full report details. Supports date-range filtering and configurable result limits. **Requires x402 payment of $0.15 USDC on Base or Bearer API key.**", "operationId": "getForensicsReports", "security": [ { "x402": [] }, { "bearerApiKey": [] } ], "x-x402": { "price": "$0.15", "network": "base" }, "parameters": [ { "$ref": "#/components/parameters/wallet" }, { "name": "limit", "in": "query", "required": false, "description": "Number of reports to return (1-100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "description": "Return reports after this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "before", "in": "query", "required": false, "description": "Return reports before this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Forensics report feed returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForensicsReportsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/forensics/timeline": { "get": { "tags": [ "forensics" ], "summary": "DJD Forensics merged timeline", "description": "Returns a merged timeline of score snapshots and fraud incidents for a wallet. Supports date-range filtering and configurable result limits. **Requires x402 payment of $0.20 USDC on Base or Bearer API key.**", "operationId": "getForensicsTimeline", "security": [ { "x402": [] }, { "bearerApiKey": [] } ], "x-x402": { "price": "$0.20", "network": "base" }, "parameters": [ { "$ref": "#/components/parameters/wallet" }, { "name": "limit", "in": "query", "required": false, "description": "Number of combined events to return (1-100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "description": "Return events after this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "before", "in": "query", "required": false, "description": "Return events before this ISO 8601 date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Merged forensics timeline returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForensicsTimelineResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "description": "No forensics data found for this wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/certification/apply": { "post": { "tags": [ "certification" ], "summary": "Apply for certification", "description": "Apply for Certified Agent Badge. Requirements: active (non-expired) score, composite score >= 75, and a registered agent. Certification is valid for 1 year. **Requires x402 payment of $99 USDC on Base or Bearer API key.**", "operationId": "applyCertification", "security": [ { "x402": [] }, { "bearerApiKey": [] } ], "x-x402": { "price": "$99.00", "network": "base" }, "responses": { "201": { "description": "Certification granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificationGrantedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "description": "Wallet already has an active certification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/certification/{wallet}": { "get": { "tags": [ "certification" ], "summary": "Check certification status", "description": "Returns the active certification details for a wallet. Free — no payment required.", "operationId": "getCertificationStatus", "parameters": [ { "name": "wallet", "in": "path", "required": true, "description": "Ethereum wallet address", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "responses": { "200": { "description": "Active certification found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificationStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "No active certification found for this wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/certification/badge/{wallet}": { "get": { "tags": [ "certification" ], "summary": "SVG certification badge", "description": "Returns an embeddable shields.io-style SVG badge showing the wallet's certification status. Green if certified, gray if not. Cached for 1 hour. Free — no payment required.", "operationId": "getCertificationBadge", "parameters": [ { "name": "wallet", "in": "path", "required": true, "description": "Ethereum wallet address", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "responses": { "200": { "description": "SVG badge image", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/certification/admin/all": { "get": { "tags": [ "certification" ], "summary": "List all certifications (admin)", "description": "Returns all certifications including revoked ones. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "listAllCertifications", "security": [ { "adminKey": [] } ], "responses": { "200": { "description": "All certifications returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "certifications": { "type": "array", "items": { "$ref": "#/components/schemas/CertificationAdminItem" } }, "count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/certification/admin/{id}/revoke": { "post": { "tags": [ "certification" ], "summary": "Revoke certification (admin)", "description": "Revokes an active certification. Optionally provide a reason. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "revokeCertification", "security": [ { "adminKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Certification ID", "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for revocation (defaults to 'Administrative revocation')" } } }, "example": { "reason": "Score dropped below threshold" } } } }, "responses": { "200": { "description": "Certification revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Certification revoked" }, "id": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Certification not found or already revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/certification/admin/revenue": { "get": { "tags": [ "certification" ], "summary": "Revenue summary (admin)", "description": "Returns certification revenue summary including total, active, and revoked counts, gross and net revenue, and monthly breakdown. **Requires admin authentication (X-ADMIN-KEY header).**", "operationId": "getCertificationRevenue", "security": [ { "adminKey": [] } ], "responses": { "200": { "description": "Revenue summary returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificationRevenueResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "parameters": { "wallet": { "name": "wallet", "in": "query", "required": true, "description": "Base wallet address (EIP-55 checksummed or lowercase)", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "example": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528" }, "X-Request-ID": { "name": "X-Request-ID", "in": "header", "required": false, "description": "Client-provided request ID for tracing. If omitted, the server generates a UUID v4. Returned in the X-Request-ID response header.", "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "description": "Optional additional context", "additionalProperties": true } }, "required": [ "code", "message" ] } } }, "BasicScoreResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "tier": { "type": "string", "enum": [ "Unverified", "Emerging", "Established", "Trusted", "Elite" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "recommendation": { "type": "string", "enum": [ "proceed", "proceed_with_caution", "insufficient_history", "high_risk", "flagged_for_review", "rpc_unavailable" ] }, "modelVersion": { "type": "string" }, "lastUpdated": { "type": "string", "format": "date-time" }, "computedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of when the score was computed (may differ from lastUpdated when served from cache)" }, "scoreFreshness": { "type": "number", "minimum": 0, "maximum": 1, "description": "Freshness factor: 1 = just computed, decays linearly toward 0 at cache expiry. Consumers can use this to weight trust." }, "stale": { "type": "boolean", "description": "True when RPC was unavailable and a cached result was returned" } } }, "FullScoreResponse": { "allOf": [ { "$ref": "#/components/schemas/BasicScoreResponse" }, { "type": "object", "properties": { "sybilFlag": { "type": "boolean" }, "gamingIndicators": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": "object", "properties": { "reliability": { "$ref": "#/components/schemas/Dimension" }, "viability": { "$ref": "#/components/schemas/Dimension" }, "identity": { "$ref": "#/components/schemas/Dimension" }, "capability": { "$ref": "#/components/schemas/Dimension" } } }, "dataAvailability": { "type": "object", "properties": { "transactionHistory": { "type": "string" }, "walletAge": { "type": "string" }, "economicData": { "type": "string" }, "identityData": { "type": "string" }, "communityData": { "type": "string" } } }, "improvementPath": { "type": "array", "items": { "type": "string" } }, "scoreHistory": { "type": "array", "items": { "type": "object", "properties": { "score": { "type": "integer" }, "calculatedAt": { "type": "string", "format": "date-time" }, "modelVersion": { "type": "string" } } } } } } ] }, "Dimension": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "data": { "type": "object" } } }, "RegisterBody": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "description": "Wallet address to register" }, "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "github_url": { "type": "string", "format": "uri", "maxLength": 200 }, "website_url": { "type": "string", "format": "uri", "maxLength": 200 } } }, "RegisterResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "status": { "type": "string", "enum": [ "registered", "updated" ] }, "registeredAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "github_url": { "type": "string", "nullable": true }, "website_url": { "type": "string", "nullable": true }, "github_verified": { "type": "boolean" }, "github_stars": { "type": "integer", "nullable": true }, "github_pushed_at": { "type": "string", "nullable": true } } }, "LeaderboardResponse": { "type": "object", "properties": { "leaderboard": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "wallet": { "type": "string" }, "score": { "type": "integer" }, "tier": { "type": "string" }, "daysAlive": { "type": "integer" }, "isRegistered": { "type": "boolean" }, "githubVerified": { "type": "boolean" } } } }, "totalAgentsScored": { "type": "integer" }, "totalAgentsRegistered": { "type": "integer" }, "lastUpdated": { "type": "string", "format": "date-time" } } }, "ReportResponse": { "type": "object", "properties": { "reportId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "accepted" ] }, "targetCurrentScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "penaltyApplied": { "type": "integer" } } }, "RatingRequest": { "type": "object", "required": [ "rated_wallet", "tx_hash", "rating" ], "properties": { "rated_wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Wallet being rated" }, "tx_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "Indexed transaction hash between payer and rated wallet" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Star rating from 1 to 5" }, "comment": { "type": "string", "maxLength": 500, "description": "Optional comment about the transaction" } } }, "RatingResponse": { "type": "object", "properties": { "ratingId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "accepted" ] }, "ratedWallet": { "type": "string" }, "txHash": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "averageRating": { "type": "number" }, "ratingCount": { "type": "integer" } } }, "BlacklistResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "reported": { "type": "boolean", "description": "True if the wallet has active fraud reports" }, "reportCount": { "type": "integer" }, "mostRecentDate": { "type": "string", "format": "date-time", "nullable": true }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Unique report reason categories" }, "disputeStatus": { "type": "string", "enum": [ "none", "open", "resolved" ], "description": "Aggregate dispute state for reports filed against this wallet" } } }, "DataDecayResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "current_score": { "type": "integer", "nullable": true }, "current_tier": { "type": "string", "nullable": true }, "decay": { "type": "array", "items": { "type": "object", "properties": { "score": { "type": "integer" }, "recorded_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" }, "returned": { "type": "integer" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true } } }, "trend": { "type": "object", "nullable": true, "properties": { "direction": { "type": "string", "enum": [ "improving", "declining", "stable" ] }, "change_pct": { "type": "number" }, "avg_score": { "type": "number" }, "min_score": { "type": "integer" }, "max_score": { "type": "integer" } } }, "trajectory": { "type": "object", "properties": { "velocity": { "type": "number", "nullable": true }, "momentum": { "type": "number", "nullable": true }, "direction": { "type": "string", "enum": [ "improving", "declining", "stable", "volatile", "new" ] }, "volatility": { "type": "number" }, "modifier": { "type": "integer" }, "dataPoints": { "type": "integer" }, "spanDays": { "type": "number" } } } } }, "DataGraphCounterparty": { "type": "object", "properties": { "rank": { "type": "integer" }, "wallet": { "type": "string" }, "tx_count_outbound": { "type": "integer" }, "tx_count_inbound": { "type": "integer" }, "total_tx_count": { "type": "integer" }, "volume_outbound": { "type": "number" }, "volume_inbound": { "type": "number" }, "total_volume": { "type": "number" }, "first_interaction": { "type": "string", "format": "date-time" }, "last_interaction": { "type": "string", "format": "date-time" } } }, "DataGraphResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "current_score": { "type": "integer", "nullable": true }, "current_tier": { "type": "string", "nullable": true }, "sybil_flagged": { "type": "boolean" }, "counterparties": { "type": "array", "items": { "$ref": "#/components/schemas/DataGraphCounterparty" } }, "count": { "type": "integer" }, "returned": { "type": "integer" }, "summary": { "type": "object", "properties": { "counterparty_count": { "type": "integer" }, "outbound_tx_count": { "type": "integer" }, "inbound_tx_count": { "type": "integer" }, "total_tx_count": { "type": "integer" }, "volume_outbound": { "type": "number" }, "volume_inbound": { "type": "number" }, "total_volume": { "type": "number" }, "first_interaction": { "type": "string", "format": "date-time", "nullable": true }, "last_interaction": { "type": "string", "format": "date-time", "nullable": true } } } } }, "DataRatingsBreakdown": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "count": { "type": "integer" } } }, "DataRatingsItem": { "type": "object", "properties": { "rating_id": { "type": "string", "format": "uuid" }, "rater_wallet": { "type": "string" }, "tx_hash": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "comment": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "DataRatingsResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "current_score": { "type": "integer", "nullable": true }, "current_tier": { "type": "string", "nullable": true }, "average_rating": { "type": "number" }, "rating_count": { "type": "integer" }, "unique_raters": { "type": "integer" }, "most_recent_rating_at": { "type": "string", "format": "date-time", "nullable": true }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/DataRatingsBreakdown" } }, "ratings": { "type": "array", "items": { "$ref": "#/components/schemas/DataRatingsItem" } }, "count": { "type": "integer" }, "returned": { "type": "integer" } } }, "FraudDisputeRequest": { "type": "object", "required": [ "report_id", "reason", "details" ], "properties": { "report_id": { "type": "string", "description": "Fraud report ID from the reports or feed endpoints" }, "reason": { "type": "string", "enum": [ "fulfilled_service", "mistaken_identity", "resolved_offchain", "inaccurate_report", "other" ] }, "details": { "type": "string", "description": "Supporting explanation or evidence for the dispute" } } }, "FraudDisputeResponse": { "type": "object", "properties": { "disputeId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open" ] }, "reportId": { "type": "string" }, "targetWallet": { "type": "string" } } }, "ApiKeyCreatedResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "Auto-incremented key ID" }, "key": { "type": "string", "description": "The raw API key (djd_live_...) — returned ONLY on creation" }, "key_prefix": { "type": "string", "description": "First 16 characters of the key for identification" }, "wallet": { "type": "string" }, "name": { "type": "string", "nullable": true }, "tier": { "type": "string" }, "monthly_limit": { "type": "integer" }, "usage_reset_at": { "type": "string", "format": "date-time" }, "message": { "type": "string" } } }, "ApiKeyListItem": { "type": "object", "properties": { "id": { "type": "integer" }, "key_prefix": { "type": "string" }, "wallet": { "type": "string" }, "name": { "type": "string", "nullable": true }, "tier": { "type": "string" }, "monthly_limit": { "type": "integer" }, "monthly_used": { "type": "integer" }, "usage_reset_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "integer", "enum": [ 0, 1 ] }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } } }, "WebhookCreatedResponse": { "type": "object", "properties": { "id": { "type": "integer" }, "wallet": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string", "description": "HMAC secret for verifying webhook signatures — returned ONLY on creation" }, "events": { "type": "array", "items": { "type": "string" } }, "threshold_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "forensics_filter": { "$ref": "#/components/schemas/WebhookForensicsFilter" }, "presets_applied": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string" }, "message": { "type": "string" } } }, "PublicWebhookCreatedResponse": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "secret": { "type": "string", "description": "HMAC secret for verifying webhook signatures — returned ONLY on creation" }, "events": { "type": "array", "items": { "type": "string" } }, "threshold_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "forensics_filter": { "$ref": "#/components/schemas/WebhookForensicsFilter" }, "presets_applied": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } }, "WebhookListItem": { "type": "object", "properties": { "id": { "type": "integer" }, "wallet": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string" }, "threshold_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "forensics_filter": { "$ref": "#/components/schemas/WebhookForensicsFilter" }, "is_active": { "type": "integer", "enum": [ 0, 1 ] }, "created_at": { "type": "string", "format": "date-time" }, "failure_count": { "type": "integer" }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "disabled_at": { "type": "string", "format": "date-time", "nullable": true } } }, "PublicWebhookListItem": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string" }, "threshold_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "forensics_filter": { "$ref": "#/components/schemas/WebhookForensicsFilter" }, "is_active": { "type": "integer", "enum": [ 0, 1 ] }, "created_at": { "type": "string", "format": "date-time" }, "failure_count": { "type": "integer" }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true } } }, "WebhookDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookCreatedResponse" }, { "type": "object", "properties": { "is_active": { "type": "integer", "enum": [ 0, 1 ] }, "created_at": { "type": "string", "format": "date-time" }, "failure_count": { "type": "integer" }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "disabled_at": { "type": "string", "format": "date-time", "nullable": true }, "recent_deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "event_type": { "type": "string" }, "status_code": { "type": "integer", "nullable": true }, "attempt": { "type": "integer" }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } ] }, "WebhookPreset": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "score_monitoring", "forensics_monitoring", "forensics_disputes", "forensics_watchlist", "anomaly_monitoring" ] }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "threshold_score_default": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true } } }, "WebhookForensicsFilter": { "type": "object", "nullable": true, "properties": { "minimum_risk_level": { "type": "string", "enum": [ "clear", "watch", "elevated", "critical" ], "description": "Only emit Forensics events whose resulting risk level meets or exceeds this threshold." }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "failed_delivery", "payment_fraud", "impersonation", "malicious_behavior", "other" ] }, "description": "Only emit Forensics events tied to these report reasons." } } }, "MonitoringPreset": { "type": "object", "properties": { "policy_type": { "type": "string", "enum": [ "score_monitoring", "forensics_monitoring", "forensics_disputes", "forensics_watchlist", "anomaly_monitoring" ] }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "threshold_score_default": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "supports_threshold_score": { "type": "boolean" }, "supports_forensics_filter": { "type": "boolean" } } }, "MonitoringSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "target_wallet": { "type": "string" }, "policy_type": { "type": "string", "enum": [ "score_monitoring", "forensics_monitoring", "forensics_disputes", "forensics_watchlist", "anomaly_monitoring" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "threshold_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "forensics_filter": { "$ref": "#/components/schemas/WebhookForensicsFilter" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "disabled_at": { "type": "string", "format": "date-time", "nullable": true }, "failure_count": { "type": "integer" }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true } } }, "MonitoringSubscriptionCreatedResponse": { "allOf": [ { "$ref": "#/components/schemas/MonitoringSubscription" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "HMAC secret for verifying webhook signatures — returned ONLY on creation" }, "presets_applied": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } } ] }, "ScoreHistoryResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "model_version": { "type": "string" }, "calculated_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer", "description": "Total records matching the query" }, "returned": { "type": "integer", "description": "Number of records in this response" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true } } }, "trend": { "type": "object", "nullable": true, "description": "Trend analysis (present when 2+ data points exist)", "properties": { "direction": { "type": "string", "enum": [ "improving", "declining", "stable" ] }, "change_pct": { "type": "number", "description": "Percentage change from earliest to latest score" }, "avg_score": { "type": "number" }, "min_score": { "type": "integer" }, "max_score": { "type": "integer" } } } } }, "ForensicsOverviewResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "risk_level": { "type": "string", "enum": [ "clear", "watch", "elevated", "critical" ] }, "current_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "current_tier": { "type": "string", "nullable": true }, "report_count": { "type": "integer" }, "total_penalty_applied": { "type": "integer" }, "unique_reporters": { "type": "integer" }, "most_recent_report_at": { "type": "string", "format": "date-time", "nullable": true }, "dispute_status": { "type": "string", "enum": [ "none", "open", "resolved" ] }, "open_disputes": { "type": "integer" }, "resolved_disputes": { "type": "integer" }, "score_history_entries": { "type": "integer" }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "count": { "type": "integer" } } } }, "recent_reports": { "type": "array", "items": { "type": "object", "properties": { "report_id": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "penalty_applied": { "type": "integer" } } } } } }, "ForensicsTimelineResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "risk_level": { "type": "string", "enum": [ "clear", "watch", "elevated", "critical" ] }, "events": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "score_snapshot" ] }, "timestamp": { "type": "string", "format": "date-time" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "model_version": { "type": "string" } } }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "fraud_report" ] }, "timestamp": { "type": "string", "format": "date-time" }, "report_id": { "type": "string" }, "reason": { "type": "string" }, "penalty_applied": { "type": "integer" } } } ] } }, "count": { "type": "integer", "description": "Total combined events matching the query" }, "returned": { "type": "integer", "description": "Number of events in this response" }, "breakdown": { "type": "object", "properties": { "score_snapshots": { "type": "integer" }, "fraud_reports": { "type": "integer" } } }, "report_summary": { "type": "object", "properties": { "report_count": { "type": "integer" }, "total_penalty_applied": { "type": "integer" } } }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true } } }, "trend": { "type": "object", "nullable": true, "properties": { "direction": { "type": "string", "enum": [ "improving", "declining", "stable" ] }, "change_pct": { "type": "number" }, "avg_score": { "type": "number" }, "min_score": { "type": "integer" }, "max_score": { "type": "integer" } } }, "trajectory": { "type": "object", "properties": { "velocity": { "type": "number", "nullable": true }, "momentum": { "type": "number", "nullable": true }, "direction": { "type": "string", "enum": [ "improving", "declining", "stable", "volatile", "new" ] }, "volatility": { "type": "number" }, "modifier": { "type": "integer" }, "dataPoints": { "type": "integer" }, "spanDays": { "type": "number" } } } } }, "ForensicsReportsResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "risk_level": { "type": "string", "enum": [ "clear", "watch", "elevated", "critical" ] }, "reports": { "type": "array", "items": { "type": "object", "properties": { "report_id": { "type": "string" }, "reason": { "type": "string" }, "details": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "penalty_applied": { "type": "integer" } } } }, "count": { "type": "integer", "description": "Total reports matching the query" }, "returned": { "type": "integer", "description": "Number of reports in this response" }, "unique_reporters": { "type": "integer" }, "total_penalty_applied": { "type": "integer" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true } } } } }, "ForensicsWatchlistResponse": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "wallet": { "type": "string" }, "risk_level": { "type": "string", "enum": [ "clear", "watch", "elevated", "critical" ] }, "current_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "current_tier": { "type": "string", "nullable": true }, "report_count": { "type": "integer" }, "unique_reporters": { "type": "integer" }, "total_penalty_applied": { "type": "integer" }, "most_recent_report_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer", "description": "Total wallets matching the query" }, "returned": { "type": "integer", "description": "Number of wallets in this response" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true } } } } }, "ForensicsFeedResponse": { "type": "object", "properties": { "incidents": { "type": "array", "items": { "type": "object", "properties": { "report_id": { "type": "string" }, "wallet": { "type": "string" }, "reason": { "type": "string" }, "details": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "penalty_applied": { "type": "integer" }, "current_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "current_tier": { "type": "string", "nullable": true }, "risk_level": { "type": "string", "enum": [ "clear", "watch", "elevated", "critical" ] }, "report_count": { "type": "integer" }, "unique_reporters": { "type": "integer" }, "total_penalty_applied": { "type": "integer" } } } }, "count": { "type": "integer", "description": "Total incidents matching the query" }, "returned": { "type": "integer", "description": "Number of incidents in this response" }, "reason_filter": { "type": "string", "nullable": true }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time", "nullable": true } } } } }, "CertificationGrantedResponse": { "type": "object", "properties": { "id": { "type": "integer" }, "wallet": { "type": "string" }, "tier": { "type": "string" }, "score_at_certification": { "type": "integer" }, "granted_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "message": { "type": "string" } } }, "CertificationStatusResponse": { "type": "object", "properties": { "wallet": { "type": "string" }, "tier": { "type": "string" }, "score_at_certification": { "type": "integer" }, "granted_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "is_valid": { "type": "boolean" } } }, "CertificationAdminItem": { "type": "object", "properties": { "id": { "type": "integer" }, "wallet": { "type": "string" }, "tier": { "type": "string" }, "score_at_certification": { "type": "integer" }, "granted_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "revocation_reason": { "type": "string", "nullable": true } } }, "CertificationRevenueResponse": { "type": "object", "properties": { "total_certifications": { "type": "integer" }, "active_certifications": { "type": "integer" }, "revoked_certifications": { "type": "integer" }, "gross_revenue_usd": { "type": "number" }, "net_revenue_usd": { "type": "number" }, "price_per_cert_usd": { "type": "integer", "example": 99 }, "by_month": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "example": "2026-02" }, "count": { "type": "integer" }, "revoked_count": { "type": "integer" }, "gross_revenue_usd": { "type": "number" }, "net_revenue_usd": { "type": "number" } } } } } } }, "responses": { "BadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "x402 payment required. The response includes a WWW-Authenticate header with payment details. Use an x402-compatible client to pay and retry.", "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } } }, "RateLimited": { "description": "Rate limit exceeded (120 requests/hour per payer wallet on paid endpoints)", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests per window" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in current window" }, "RateLimit-Reset": { "schema": { "type": "string", "format": "date-time" }, "description": "When the current window resets" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until rate limit resets" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "FreeTierExhausted": { "description": "Free tier daily quota exhausted (10 requests/day). Upgrade to paid x402 for unlimited access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "upgrade": { "type": "object", "properties": { "docs": { "type": "string" }, "pricing": { "type": "object" }, "protocol": { "type": "string" }, "network": { "type": "string" } } } } } } } } }, "securitySchemes": { "x402": { "type": "http", "scheme": "x402", "description": "x402 micropayment protocol (EIP-3009 USDC transferWithAuthorization on Base). See https://www.x402.org for client libraries." }, "adminKey": { "type": "apiKey", "in": "header", "name": "x-admin-key", "description": "Admin API key for management endpoints" }, "bearerApiKey": { "type": "http", "scheme": "bearer", "description": "API key authentication (Bearer djd_live_...)" } } } }