{
  "openapi": "3.1.0",
  "info": {
    "title": "Wired API",
    "version": "1.0.0",
    "description": "Neural networks that run inside smart contracts on Robinhood Chain (4663). Every inference is computed by the chain: the API only reads it and returns the exact call so you can replay it. The API holds no keys and sends no transactions; it returns the ones to sign."
  },
  "externalDocs": {
    "url": "https://www.usewired.net/docs/api"
  },
  "servers": [
    {
      "url": "https://www.usewired.net/api/v1"
    }
  ],
  "paths": {
    "/models": {
      "get": {
        "summary": "List every model in the registry",
        "responses": {
          "200": {
            "description": "Newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "models": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Chain unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/models/{id}": {
      "get": {
        "summary": "Read one model",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{64}$",
              "description": "Model id: keccak256 of the code hashes of its blobs."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The model",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Chain unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/models/{id}/infer": {
      "post": {
        "summary": "Ask the model, onchain",
        "description": "Runs `classify(id, input)` on the registry with eth_call at the latest block. Send `input` (int8) or `values` (real numbers, quantized with the scale the model publishes onchain).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{64}$",
              "description": "Model id: keccak256 of the code hashes of its blobs."
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input": {
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": -128,
                          "maximum": 127
                        }
                      },
                      {
                        "type": "string",
                        "pattern": "^0x[0-9a-fA-F]*$"
                      }
                    ],
                    "description": "One int8 per value, or hex bytes."
                  },
                  "values": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Real values; x_int8 = round(x / scale), clamped to ±127."
                  }
                }
              },
              "example": {
                "input": [
                  0,
                  0,
                  64,
                  127
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Answer"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by the chain or the compiler",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Chain unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Ask the model, onchain (query string)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{64}$",
              "description": "Model id: keccak256 of the code hashes of its blobs."
            }
          },
          {
            "name": "input",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated int8 values, or 0x hex."
          },
          {
            "name": "values",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated real values."
          }
        ],
        "responses": {
          "200": {
            "description": "The answer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Answer"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by the chain or the compiler",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Chain unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/compile": {
      "post": {
        "summary": "Compile an ONNX network to a Wired int8 model",
        "description": "Dense layers with ReLU (Gemm, or MatMul + Add). Parsing stops at Softmax or ArgMax. Body limit 4.5 MB: compile larger models in the browser on /deploy.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "model"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "format": "binary",
                    "description": "The .onnx file."
                  },
                  "inputMin": {
                    "type": "number",
                    "description": "Smallest real input value."
                  },
                  "inputMax": {
                    "type": "number",
                    "description": "Largest real input value."
                  },
                  "inputScale": {
                    "type": "number",
                    "description": "Instead of inputMin/inputMax: the real value of one int8 unit."
                  },
                  "calib": {
                    "type": "string",
                    "format": "binary",
                    "description": ".npy of real inputs (rows × inputs) to calibrate hidden layers."
                  },
                  "testX": {
                    "type": "string",
                    "format": "binary",
                    "description": ".npy test inputs."
                  },
                  "testY": {
                    "type": "string",
                    "format": "binary",
                    "description": ".npy test classes."
                  },
                  "labels": {
                    "type": "string",
                    "description": "Comma-separated, one per output."
                  },
                  "shape": {
                    "type": "string",
                    "description": "Logical input shape, e.g. 28x28."
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The compiled model",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^0x[0-9a-fA-F]{64}$",
                      "description": "Model id: keccak256 of the code hashes of its blobs."
                    },
                    "registered": {
                      "type": "boolean",
                      "description": "True if these exact weights are already onchain."
                    },
                    "layers": {
                      "type": "array",
                      "items": {
                        "type": "array",
                        "items": {
                          "type": "integer"
                        }
                      }
                    },
                    "params": {
                      "type": "integer"
                    },
                    "blobs": {
                      "type": "integer",
                      "description": "Contracts needed to store the weights."
                    },
                    "metrics": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "model": {
                      "type": "object",
                      "description": "The .wired.json, ready for /deploy."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by the chain or the compiler",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Chain unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/deploy": {
      "post": {
        "summary": "Prepare the transactions that put a model onchain",
        "description": "Returns unsigned transactions for `from`, in order with nonces: one contract per weight blob, then `register`. The registration is simulated onchain first.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "from",
                  "model"
                ],
                "properties": {
                  "from": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$"
                  },
                  "model": {
                    "type": "object",
                    "description": "A .wired.json, or the whole /compile response."
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transactions to sign, or the existing model",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^0x[0-9a-fA-F]{64}$",
                      "description": "Model id: keccak256 of the code hashes of its blobs."
                    },
                    "registered": {
                      "type": "boolean"
                    },
                    "transactions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Tx"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by the chain or the compiler",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Chain unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/arena": {
      "get": {
        "summary": "Arena contract, match count and the brain format",
        "responses": {
          "200": {
            "description": "Arena info"
          },
          "502": {
            "description": "Chain unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/arena/matches/{id}": {
      "get": {
        "summary": "Read a match: players, heads, grid, pot",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The match"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Chain unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{64}$",
            "description": "Model id: keccak256 of the code hashes of its blobs."
          },
          "name": {
            "type": "string"
          },
          "owner": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "inputLen": {
            "type": "integer"
          },
          "outputLen": {
            "type": "integer"
          },
          "labels": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "input": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "shape": {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              },
              "scale": {
                "type": "number"
              },
              "encoding": {
                "type": "string"
              }
            }
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "metrics": {
            "type": [
              "object",
              "null"
            ]
          },
          "registeredAt": {
            "type": "string",
            "format": "date-time"
          },
          "decisions": {
            "type": "integer",
            "description": "Times `decide` logged an answer onchain."
          },
          "blobs": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          },
          "page": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Answer": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{64}$",
            "description": "Model id: keccak256 of the code hashes of its blobs."
          },
          "label": {
            "type": "integer",
            "description": "Index of the first highest logit."
          },
          "labelName": {
            "type": [
              "string",
              "null"
            ]
          },
          "logits": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "gasUsed": {
            "type": "integer",
            "description": "Gas of the registry call, measured onchain."
          },
          "block": {
            "type": "string",
            "description": "Block the call ran at."
          },
          "input": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]*$"
          },
          "call": {
            "type": "object",
            "description": "eth_call this at `block` on 0x320D078b873912cf8dDe00f750fd16240C457ca7 to replay the answer.",
            "properties": {
              "to": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              "data": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]*$"
              }
            }
          },
          "decide": {
            "$ref": "#/components/schemas/Tx"
          }
        }
      },
      "Tx": {
        "type": "object",
        "properties": {
          "step": {
            "type": "string"
          },
          "chainId": {
            "type": "integer",
            "const": 4663
          },
          "from": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "nonce": {
            "type": "integer"
          },
          "to": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              {
                "type": "null"
              }
            ],
            "description": "null creates a contract."
          },
          "value": {
            "type": "string"
          },
          "data": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]*$"
          },
          "creates": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "description": "Address of the contract this creates."
          }
        }
      }
    }
  }
}