{
  "openapi": "3.1.0",
  "info": {
    "title": "Crypterian",
    "version": "1.0.0",
    "description": "**Live on Base + Solana mainnet — USDC settles to production addresses via the Coinbase (CDP) x402 facilitator.** Reputation engine for autonomous agents. Returns a 0-100 reliability score (computed from observed on-chain behavior), tier, and observed-activity stats for an on-chain agent wallet — ERC-4337 smart accounts on Base, agent-controlled wallets on Solana. Wallets with fewer than 100 observed events return tier='unranked' — we never fabricate scores without evidence. Full scoring formula, tier mapping, and behavioral profile taxonomy are public at https://crypterian.io/methodology/. Server-side integration only: no CORS / X-PAYMENT preflight is supported because the intended consumer is a server-side bot agent.",
    "contact": {
      "name": "Jamhimself LLC (Crypterian)",
      "url": "https://crypterian.io"
    },
    "license": {
      "name": "Proprietary — © Jamhimself LLC"
    }
  },
  "servers": [
    {
      "url": "https://crypterian.io",
      "description": "Production — Base + Solana mainnet (USDC via the Coinbase CDP x402 facilitator)"
    }
  ],
  "paths": {
    "/score/{wallet}": {
      "get": {
        "summary": "Get the reliability score for an on-chain agent wallet",
        "description": "x402-paywalled. Auto-detects chain from the wallet format (Base 0x-style EOA address vs Solana base58). Accepts USDC payment on Base mainnet (eip155:8453) or Solana mainnet — buyer picks; settled to production addresses via the Coinbase (CDP) x402 facilitator.$0.005 USDC per request.",
        "operationId": "getScore",
        "parameters": [
          {
            "name": "wallet",
            "in": "path",
            "required": true,
            "description": "Wallet address — either EVM 0x… (40 hex) for Base or base58 (32-44 chars) for Solana.",
            "schema": {
              "type": "string",
              "pattern": "^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$"
            },
            "examples": {
              "base": {
                "summary": "Base smart account",
                "value": "0xabcdef1234567890abcdef1234567890abcdef12"
              },
              "solana": {
                "summary": "Solana agent wallet",
                "value": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Score for the requested wallet. Returned only after a successful x402 payment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScoreResponse"
                },
                "examples": {
                  "ranked": {
                    "summary": "Wallet with sufficient observed events",
                    "value": {
                      "wallet": "0xabcdef1234567890abcdef1234567890abcdef12",
                      "chain": "base",
                      "score": 96,
                      "tier": "S",
                      "confidence": 1.0,
                      "txn_count": 142,
                      "last_seen": "2026-05-12T18:21:41Z"
                    }
                  },
                  "unranked": {
                    "summary": "Wallet with insufficient evidence",
                    "value": {
                      "wallet": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
                      "chain": "solana",
                      "score": 85,
                      "tier": "unranked",
                      "confidence": 0.5,
                      "txn_count": 50,
                      "last_seen": "2026-05-07T11:01:33Z"
                    }
                  },
                  "unobserved": {
                    "summary": "Wallet we have never seen on-chain",
                    "value": {
                      "wallet": "0x0000000000000000000000000000000000000abc",
                      "chain": "base",
                      "score": null,
                      "tier": "unranked",
                      "confidence": 0,
                      "txn_count": 0,
                      "last_seen": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid wallet address format.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "402": {
            "description": "Payment Required — x402 challenge. The `Payment-Required` header contains a base64-encoded payload listing accepted payment schemes (Base + Solana, USDC at $0.005/call). Pay one of them and retry with an `X-Payment` header containing the settlement proof.",
            "headers": {
              "Payment-Required": {
                "description": "Base64-encoded JSON containing payment requirements per x402 protocol (v2). Includes accepts[], bazaar discovery metadata, and resource URL.",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/enriched-score/{wallet}": {
      "get": {
        "summary": "Get the enriched reputation report for an on-chain agent wallet",
        "description": "Mid-tier endpoint at $0.02/call. Returns everything `/score/{wallet}` does PLUS: percentile rank within the wallet's tier (solves \"everyone is S — which S is best?\"), 90-day behavioral fingerprint from decoded callData (distinct target contracts, distinct paymasters, top 5 inner-call selectors with labels, decoder coverage %), and a reserved slot for reliability_30d / reliability_90d that populates as the scoring cron computes them. Designed for onboarding decisions (\"should I add this wallet to my recurring-partner whitelist?\") rather than runtime scoring. Same x402 challenge mechanics as /score; auto-detects chain from wallet format.",
        "operationId": "getEnrichedScore",
        "parameters": [
          {
            "name": "wallet",
            "in": "path",
            "required": true,
            "description": "Wallet address — either EVM 0x… (40 hex) for Base or base58 (32-44 chars) for Solana.",
            "schema": {
              "type": "string",
              "pattern": "^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Enriched reputation report. Returned only after a successful x402 payment of $0.02 USDC.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EnrichedScoreResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid wallet address format.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "402": {
            "description": "Payment Required — x402 challenge at $0.02 USDC. Same protocol mechanics as `/score/{wallet}`, different price.",
            "headers": {
              "Payment-Required": {
                "description": "Base64-encoded JSON containing payment requirements per x402 protocol (v2).",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ScoreResponse": {
        "type": "object",
        "required": ["wallet", "chain", "tier", "confidence", "txn_count", "disclaimer"],
        "additionalProperties": false,
        "properties": {
          "wallet": {
            "type": "string",
            "description": "The queried wallet address (canonicalized — lowercased for Base, preserved-case for Solana)."
          },
          "chain": {
            "type": "string",
            "enum": ["base", "solana"],
            "description": "Chain the wallet lives on. Auto-detected from address format."
          },
          "score": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 100,
            "description": "Reliability score 0-100, computed from observed on-chain behavior. Null if we have never observed the wallet on-chain."
          },
          "tier": {
            "type": "string",
            "enum": ["S", "A", "B", "C", "D", "unranked"],
            "description": "S = 95+, A = 90-94, B = 80-89, C = 60-79, D = <60. 'unranked' when the wallet has fewer than 100 observed events (regardless of score). We do not fabricate tier signal without sufficient evidence."
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "min(txn_count / 100, 1.0). Scales linearly with observed activity volume."
          },
          "txn_count": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of on-chain events Crypterian has observed for this wallet. For Base wallets this counts ERC-4337 UserOperationEvents from EntryPoint v0.6 + v0.7. For Solana wallets this counts payment-success/payment-failed signatures observed through discovered receiver activity."
          },
          "last_seen": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "Timestamp of the most recent observed on-chain event for this wallet. Null if unobserved."
          },
          "disclaimer": {
            "type": "string",
            "description": "Standing notice: an observational signal, not advice, with no warranty. Always present."
          },
          "profile": {
            "type": ["object", "null"],
            "description": "AI-inferred behavioral profile of the wallet. Refreshed every 6h for ranked wallets. Null when not yet inferred.",
            "additionalProperties": false,
            "required": ["category", "confidence", "rationale"],
            "properties": {
              "category": {
                "type": "string",
                "enum": [
                  "high_velocity_agent",
                  "paymaster_diverse",
                  "sporadic_user",
                  "low_quality_bot",
                  "sybil_pattern",
                  "dex_caller",
                  "nft_minter",
                  "bridge_user",
                  "unclassified"
                ]
              },
              "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
              "rationale": { "type": "string" },
              "computed_at": { "type": "string", "format": "date-time" },
              "model": { "type": "string" }
            }
          },
          "sybil": {
            "type": ["object", "null"],
            "description": "Cluster-level sybil verdict. Null when no cluster verdict exists. If `is_sybil` is true, this wallet appears to belong to a coordinated multi-wallet group sharing a paymaster and creation window. Buyers should filter accordingly.",
            "additionalProperties": false,
            "required": ["cluster_id", "is_sybil", "confidence", "rationale"],
            "properties": {
              "cluster_id":   { "type": "string", "description": "Stable id for the cluster (paymaster:creation_hour)." },
              "is_sybil":     { "type": "boolean" },
              "confidence":   { "type": "number", "minimum": 0, "maximum": 1 },
              "rationale":    { "type": "string" },
              "cluster_size": { "type": "integer", "minimum": 1 },
              "computed_at":  { "type": "string", "format": "date-time" },
              "model":        { "type": "string" }
            }
          }
        }
      },
      "EnrichedScoreResponse": {
        "type": "object",
        "required": [
          "wallet", "chain", "tier", "confidence", "txn_count",
          "reliability", "behavioral_fingerprint", "disclaimer"
        ],
        "additionalProperties": false,
        "description": "Same shape as ScoreResponse plus tier_rank, reliability slot, and a 90-day behavioral fingerprint derived from decoded callData. Returned by /enriched-score/{wallet} at $0.02/call.",
        "properties": {
          "wallet":     { "type": "string" },
          "chain":      { "type": "string", "enum": ["base", "solana"] },
          "score":      { "type": ["integer", "null"], "minimum": 0, "maximum": 100 },
          "tier":       { "type": "string", "enum": ["S", "A", "B", "C", "D", "unranked"] },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "txn_count":  { "type": "integer", "minimum": 0 },
          "first_seen": { "type": ["string", "null"], "format": "date-time" },
          "last_seen":  { "type": ["string", "null"], "format": "date-time" },
          "disclaimer": { "type": "string" },
          "profile":    { "type": ["object", "null"] },
          "sybil":      { "type": ["object", "null"] },
          "tier_rank": {
            "type": ["object", "null"],
            "description": "Position within the wallet's tier — solves \"everyone is S, which S is best?\". Null when tier is 'unranked'.",
            "additionalProperties": false,
            "required": ["tier_size", "rank_in_tier", "percentile_in_tier"],
            "properties": {
              "tier_size":          { "type": "integer", "minimum": 1, "description": "Total number of wallets in this tier." },
              "rank_in_tier":       { "type": "integer", "minimum": 1, "description": "1-indexed rank by score; ties share the highest rank." },
              "percentile_in_tier": { "type": "integer", "minimum": 0, "maximum": 100, "description": "What percentile of the tier this wallet is in (100 = top)." }
            }
          },
          "reliability": {
            "type": "object",
            "description": "30-day and 90-day reliability metrics computed from observed on-chain behavior. May be null while calibration is in progress; the field shape stays stable so consumers don't need to handle the transition.",
            "additionalProperties": false,
            "required": ["reliability_30d", "reliability_90d"],
            "properties": {
              "reliability_30d": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
              "reliability_90d": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
              "note":            { "type": ["string", "null"], "description": "Optional explanation when values are null (e.g. 'calibration in progress')." }
            }
          },
          "behavioral_fingerprint": {
            "type": "object",
            "description": "90-day decoder-derived behavioral signal. distinct_target_contracts and top inner_selectors come from the callData decoder pipeline — Crypterian decodes ERC-4337 handleOps + the wallet's inner execute call to surface what the wallet is actually invoking downstream of its smart account.",
            "additionalProperties": false,
            "required": [
              "distinct_target_contracts_90d", "distinct_paymasters_90d",
              "total_events_90d", "decoder_coverage_pct",
              "top_inner_selectors_90d"
            ],
            "properties": {
              "distinct_target_contracts_90d": { "type": "integer", "minimum": 0 },
              "distinct_paymasters_90d":       { "type": "integer", "minimum": 0 },
              "total_events_90d":              { "type": "integer", "minimum": 0 },
              "decoder_coverage_pct":          { "type": "integer", "minimum": 0, "maximum": 100, "description": "Percentage of total_events_90d that were successfully decoded for inner_selector. 0 when no decoded data has accumulated yet (early days after decoder deploy)." },
              "top_inner_selectors_90d": {
                "type": "array",
                "maxItems": 5,
                "description": "Top 5 most-frequent 4-byte function selectors the wallet's smart account is calling. `label` is a human-readable function name when known (e.g. 'approve' for 0x095ea7b3); null for unrecognized selectors.",
                "items": {
                  "type": "object",
                  "required": ["selector", "count"],
                  "additionalProperties": false,
                  "properties": {
                    "selector": { "type": "string", "pattern": "^0x[a-fA-F0-9]{8}$" },
                    "count":    { "type": "integer", "minimum": 1 },
                    "label":    { "type": ["string", "null"] }
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" }
        }
      }
    }
  }
}