{
  "openapi": "3.1.0",
  "info": {
    "title": "Trnch API on Elysium",
    "version": "1.0.0",
    "description": "Elysium swap aggregator for AI agents: facts read on chain about any token (not a verdict), wallet holdings with those facts, top tokens by 24-hour volume, quotes across three routers, buy and sell transactions for your own wallet to sign. Non-custodial. Facts read on chain, not a verdict: Trnch runs no rug screen on this chain."
  },
  "servers": [
    {
      "url": "https://trnch.fun/elysium/api/bot/v1"
    }
  ],
  "paths": {
    "/check": {
      "get": {
        "operationId": "check",
        "summary": "Token facts read on chain (Elysium)",
        "description": "Facts, not a verdict: Trnch runs no rug screen on this chain. sellTest: a simulation at the time of the read that tries to buy, approve, transfer wallet to wallet and back, and sell from both wallets, as separate transactions, through the pools Trnch would route through (the proven launch pool, the deepest and the oldest qualifying pool; the worst result decides: decidingPool, poolTested, checkedAt), at two sizes and again with the clock advanced 5 minutes in simulation; note says in words what actually ran, complete, variantsRun and variantsSkipped say what did not and why, and a partial result reads \"(partial check)\"; class sold (bought, transferred and sold in a simulation, every step that ran succeeded), taxed, blocked (blockedAt says whether the approval or the sell failed in the simulation), transfer-failed (the tokens could not be moved between wallets in the simulation) or not-checked; buy tax, transfer tax and sell loss are reported apart, and token logs that do not match balances are reported. A simulation now: the token may behave differently later or towards other wallets, and an upgradeable or owner-controlled token can change. Returns poolTested, checkedAt and cacheAgeSeconds. No key.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "Token contract address",
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ token, chainId, screened: false, sellTest { class, result, blockedAt, complete, variantsRun, variantsSkipped, lossPct, method, sizes [{ amount, result, class, lossPct }], extraLossPctAtLargerSize, transfer { ok, backOk, taxPct }, logsMatchBalances, delayed { clockAdvancedMinutes, result }, note }, decidingPool { id, roles, why }, poolsTested, poolsTruncated, hookFee, liquidity, creator, launchpad { result, label, hook }, template { result, label, implementation }, forcedTransfer { result, found, rolesTried, balanceChangedOverTime }, meaning }. launchpad { result, hook, proof }: the launchpad of the pool tested, named only when proven (\"Montra\", \"Boxa\", \"Kleos\"; a verified contract name alone reads \"<Name> (contract name)\"), otherwise \"hook not identified\" or \"no hook\", a fact about origin, never a signal by itself; hookRisk { result }: what the hook of that pool can take, read on chain where readable: \"launch fee window: up to N%, ends in M min\", \"hook tax: N% buy, M% sell\" or \"hook can tax up to N%\", null when there is nothing to say; template { result, implementation, upgradeable }: \"Montra template\" when the token is a clone of that launchpad's token, \"clone, template not identified\", \"upgradeable proxy\" (its code can be replaced after the read) or \"custom contract\"; forcedTransfer { result, rolesTried, callsTried }: whether the declared owner or the creator could move or burn a buyer's tokens without approval in a simulation, trying only transferFrom without allowance and burn (other owner powers are not tried), \"none found\", \"found: <reason>\" or \"not checked: <why>\". A fact that could not be read says \"not checked: <why>\".",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Chain read failed"
          }
        }
      }
    },
    "/scan": {
      "get": {
        "operationId": "scanWallet",
        "summary": "Tokens a Elysium wallet holds, with on-chain facts for the largest",
        "description": "Facts, not a verdict: Trnch runs no rug screen on this chain. No key.",
        "parameters": [
          {
            "name": "wallet",
            "in": "query",
            "required": true,
            "description": "Wallet address",
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ wallet, chainId, screened: false, truncated, partial, checked, factsLimit, tokens, meaning }",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Holdings unavailable"
          }
        }
      }
    },
    "/top": {
      "get": {
        "operationId": "topVolume",
        "summary": "Top Elysium tokens by 24-hour pool volume (GeckoTerminal)",
        "description": "Ranked by 24-hour pool volume as listed by GeckoTerminal (the Top volume list of Trade). A volume ranking, not a screen, a verdict or a recommendation. No key.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1 to 20, default 10",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ chainId, window, ranking, source, screened: false, tokens, meaning }",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "List unavailable"
          }
        }
      }
    },
    "/stats": {
      "get": {
        "operationId": "stats",
        "summary": "Chain, routers, fee grid and activity of Trnch on Elysium",
        "description": "No key.",
        "responses": {
          "200": {
            "description": "{ chainId, chain, gas, stable, routers, feePct, feePctMajorPair, activity, screened: false }",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/quote": {
      "post": {
        "operationId": "quote",
        "summary": "Quote a swap across the routers, no key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Best route and amount out, net of the Trnch fee",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/register": {
      "get": {
        "operationId": "registerMessage",
        "summary": "Message to sign for an API key",
        "parameters": [
          {
            "name": "wallet",
            "in": "query",
            "required": true,
            "description": "Agent wallet",
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ message }",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "register",
        "summary": "Create an API key from the signed message",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "{ key, prefix, wallet }"
          },
          "402": {
            "description": "Wallet holds less than 10 USDC or 0.15 HYPE"
          }
        }
      }
    },
    "/build": {
      "post": {
        "operationId": "build",
        "summary": "Build the transaction of a quoted router",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuildRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ router, amountOut, minOut, tx, approval, feeBps }",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Fee recipient not configured on this chain"
          }
        }
      }
    },
    "/buy": {
      "post": {
        "operationId": "buy",
        "summary": "Build the best buy",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ router, quote, feeBps, approval, tx, chainId, from }",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Fee recipient not configured on this chain"
          }
        }
      }
    },
    "/sell": {
      "post": {
        "operationId": "sell",
        "summary": "Build the best sell for USDC",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SellRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ router, quote, feeBps, approval, tx, chainId, from }",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Fee recipient not configured on this chain"
          }
        }
      }
    },
    "/confirm": {
      "post": {
        "operationId": "confirm",
        "summary": "Report the hash of a sent Elysium swap",
        "description": "Optional. Nothing is credited on the call. A scheduled pass (every 2 minutes) reads the transaction on Elysium: sent by the key's wallet, a swap Trnch built for it, and the Trnch fee paid to the Trnch fee recipient in that same transaction. Only then is its volume counted in the swap stats of Elysium; there are no points or rewards on this chain. A hash that does not prove all of this counts nothing.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConfirmRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ ok, txHash, chainId, chain, status: \"pending\", meaning }",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "No Trnch account for the key's wallet"
          },
          "429": {
            "description": "Rate limited, or 20 hashes already awaiting settlement for this wallet"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from /register"
      }
    },
    "schemas": {
      "QuoteRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tokenIn",
          "tokenOut",
          "amountIn"
        ],
        "properties": {
          "tokenIn": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "tokenOut": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "amountIn": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "decimalsIn": {
            "type": "integer"
          },
          "decimalsOut": {
            "type": "integer"
          },
          "slippage": {
            "type": "number"
          },
          "fast": {
            "type": "boolean"
          }
        }
      },
      "BuildRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "router",
          "tokenIn",
          "tokenOut",
          "amountIn"
        ],
        "properties": {
          "router": {
            "type": "string",
            "enum": [
              "kyberswap",
              "lifi",
              "direct"
            ]
          },
          "tokenIn": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "tokenOut": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "amountIn": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "decimalsIn": {
            "type": "integer"
          },
          "decimalsOut": {
            "type": "integer"
          },
          "slippage": {
            "type": "number"
          }
        }
      },
      "BuyRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "token"
        ],
        "properties": {
          "token": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "amountUsd": {
            "type": "number"
          },
          "amountIn": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "tokenIn": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "slippageBps": {
            "type": "integer"
          }
        }
      },
      "SellRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "token"
        ],
        "properties": {
          "token": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "percent": {
            "type": "number"
          },
          "amount": {
            "type": "string"
          },
          "slippageBps": {
            "type": "integer"
          }
        }
      },
      "ConfirmRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "txHash"
        ],
        "properties": {
          "txHash": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{64}$"
          }
        }
      },
      "RegisterRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "wallet",
          "message",
          "signature"
        ],
        "properties": {
          "wallet": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$"
          },
          "message": {
            "type": "string"
          },
          "signature": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      }
    }
  }
}