{
  "openapi": "3.1.0",
  "info": {
    "title": "Valiron Public API",
    "version": "1.0.0",
    "description": "Valiron SDK integration API. Get an operator API key from https://www.valiron.co/dashboard. Profile reads and trust operations require Authorization: Bearer val_op_.... Health, documentation, and agent key enrollment remain available without an operator key. Paid features require Pro.",
    "contact": {
      "name": "Valiron",
      "url": "https://www.valiron.co/developers"
    }
  },
  "servers": [
    {
      "url": "https://valiron-edge-proxy.onrender.com",
      "description": "Valiron hosted REST API"
    }
  ],
  "security": [],
  "externalDocs": {
    "url": "https://www.valiron.co/docs/agents/API-REFERENCE.md",
    "description": "Valiron full API reference, including webhooks"
  },
  "paths": {
    "/operator/health": {
      "get": {
        "operationId": "getOperatorHealth",
        "summary": "Valiron API health and supported networks",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "service",
                    "supportedChains",
                    "defaultChain",
                    "timestamp"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "service": {
                      "type": "string"
                    },
                    "supportedChains": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "defaultChain": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/operator/agent/{agentId}": {
      "get": {
        "operationId": "getAgentProfile",
        "summary": "Read an agent trust profile",
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "description": "ERC-8004 numeric token ID, Solana asset pubkey, or indexed Solana ID; not a local name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chain",
            "in": "query",
            "description": "Network identifier from GET /operator/health. Specify explicitly to avoid relying on the server default.",
            "schema": {
              "type": "string",
              "examples": [
                "ethereum",
                "base",
                "solana"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agentId": {
                      "type": "string"
                    },
                    "identity": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "onchainReputation": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "additionalProperties": true
                    },
                    "localReputation": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "additionalProperties": true
                    },
                    "chain": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "routing": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "timestamp": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "401": {
            "description": "Missing, invalid, or revoked operator credentials"
          }
        },
        "security": [
          {
            "OperatorApiKey": []
          }
        ],
        "description": "Authenticated identity and trust summary. Raw behavioral metrics, evidence storage links, and infrastructure URLs are not returned. Paid signal selection requires an operator key. A profile is not an access grant."
      }
    },
    "/operator/key/{agentAddress}": {
      "get": {
        "operationId": "getKeyAgentProfile",
        "summary": "Read a key-based agent profile",
        "parameters": [
          {
            "name": "agentAddress",
            "in": "path",
            "required": true,
            "description": "Ethereum-style public address of a key-based agent",
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "401": {
            "description": "Missing, invalid, or revoked operator credentials"
          }
        },
        "security": [
          {
            "OperatorApiKey": []
          }
        ]
      }
    },
    "/operator/key/{agentAddress}/icebreaker": {
      "get": {
        "operationId": "getKeyAgentIcebreaker",
        "summary": "Read private Icebreaker owner context for a verified key agent",
        "description": "A Pro operator key or the verified agent's own authenticated session is required. An agent without a session can follow the 401 challenge flow to obtain one. Returns verified profile handles, not social connections or mutuals. The attestation does not automatically change the Web2 behavioral score.",
        "security": [
          {
            "OperatorApiKey": []
          },
          {
            "AgentAddress": [],
            "AgentSession": []
          }
        ],
        "parameters": [
          {
            "name": "agentAddress",
            "in": "path",
            "required": true,
            "description": "Ethereum-style public address of a verified key-based agent",
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Icebreaker attestation and owner context, or attested false",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "agentAddress",
                    "icebreaker"
                  ],
                  "properties": {
                    "agentAddress": {
                      "type": "string"
                    },
                    "icebreaker": {
                      "type": "object",
                      "required": [
                        "attested"
                      ],
                      "properties": {
                        "attested": {
                          "type": "boolean"
                        },
                        "uid": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "owner": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "verifiedHandles": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "source",
                              "handle"
                            ],
                            "properties": {
                              "source": {
                                "type": "string"
                              },
                              "handle": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "organization": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "profileUrl": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credentialUrl": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "401": {
            "description": "Agent identity or fresh challenge proof required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/operator/key/{agentAddress}/challenge": {
      "post": {
        "operationId": "createKeyChallenge",
        "summary": "Create a key-based identity challenge",
        "parameters": [
          {
            "name": "agentAddress",
            "in": "path",
            "required": true,
            "description": "Ethereum-style public address of a key-based agent",
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "challenge": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "agentAddress": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/operator/key/verify": {
      "post": {
        "operationId": "verifyKeyChallenge",
        "summary": "Verify a signed key-based identity challenge",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "401": {
            "description": "Signature or challenge verification failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "challenge",
                  "signature",
                  "agentAddress"
                ],
                "properties": {
                  "challenge": {
                    "type": "string"
                  },
                  "signature": {
                    "type": "string"
                  },
                  "agentAddress": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/operator/gate/{agentId}": {
      "post": {
        "operationId": "evaluateAgentGate",
        "summary": "Evaluate an agent against a trust threshold",
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "description": "ERC-8004 numeric token ID, Solana asset pubkey, or indexed Solana ID; not a local name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chain",
            "in": "query",
            "description": "Network identifier from GET /operator/health. Specify explicitly to avoid relying on the server default.",
            "schema": {
              "type": "string",
              "examples": [
                "ethereum",
                "base",
                "solana"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Traffic rate limit or monthly Free allowance exhausted. Monthly rejections include code MONTHLY_REQUEST_LIMIT_EXCEEDED, used, limit, resetsAt, upgradeUrl and Retry-After."
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "401": {
            "description": "Missing or invalid operator credentials, or missing/expired/unverified agent identity"
          }
        },
        "description": "Requires an operator API key and agent challenge-response identity. Counts toward the account-wide Free allowance of 100,000 requests per UTC calendar month. Pro has no monthly request cap. Evaluate allow/deny and enforce the result at the API boundary. Paid signals require Pro.",
        "security": [
          {
            "OperatorApiKey": [],
            "AgentAddress": [],
            "AgentSession": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "minScore": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "default": 65
                  },
                  "ttlMs": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "default": 86400000
                  },
                  "trustSignals": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "8004",
                        "sandbox",
                        "world",
                        "self",
                        "icebreaker",
                        "wallet"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api": {
      "get": {
        "operationId": "getDeveloperResources",
        "summary": "Discover Valiron developer resources",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "servers": [
          {
            "url": "https://www.valiron.co"
          }
        ]
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getPublicApiHealth",
        "summary": "Check live Valiron API availability",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "service",
                    "supportedChains",
                    "defaultChain",
                    "timestamp"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "service": {
                      "type": "string"
                    },
                    "supportedChains": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "defaultChain": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "403": {
            "$ref": "#/components/responses/PlanRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "servers": [
          {
            "url": "https://www.valiron.co"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OperatorApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Operator API key (val_op_...) for metered runtime calls and paid trust signals."
      },
      "AgentAddress": {
        "type": "apiKey",
        "in": "header",
        "name": "x-agent-address",
        "description": "Verified key-based agent address."
      },
      "AgentSession": {
        "type": "apiKey",
        "in": "header",
        "name": "x-agent-session",
        "description": "Session returned after signed challenge-response on a gated request; see auth.md."
      }
    },
    "responses": {
      "InvalidInput": {
        "description": "Invalid input",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "PlanRequired": {
        "description": "Requested trust signal requires a paid plan",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "NotFound": {
        "description": "Agent not found",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limited; respect Retry-After",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "string"
            },
            "description": "Seconds before retrying"
          }
        }
      },
      "ApiError": {
        "description": "API error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "Unavailable": {
        "description": "Temporarily unavailable",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      }
    }
  }
}