{
  "openapi": "3.1.0",
  "info": {
    "title": "TRNCH Bot API",
    "version": "1.0.3",
    "summary": "Robinhood Chain trading for bots and AI agents",
    "description": "Trade new Robinhood Chain tokens (chainId 4663) through TRNCH: a live feed of launches screened by TIA (rugs, honeypots, scam contracts, heavy sell taxes and copycats are kept out and refused), and the best route across six routers (KyberSwap, LI.FI, Uniswap, 0x, SushiSwap, 1inch). Non-custodial: every transaction is returned ready to sign and is sent by your own wallet. 0.5% fee per swap, already deducted from quotes. Also available as an MCP server at https://trnch.fun/api/mcp. TRNCH data is licensed only for trading through TRNCH (https://docs.trnch.fun/legal/terms).",
    "contact": {
      "name": "TrnchLabs",
      "url": "https://trnch.fun",
      "email": "hello@trnch.fun"
    },
    "termsOfService": "https://docs.trnch.fun/legal/terms"
  },
  "externalDocs": {
    "description": "Bot API guide",
    "url": "https://trnch.fun/bot"
  },
  "servers": [
    {
      "url": "https://trnch.fun/api/bot/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "trnch_bot_..."
      }
    }
  },
  "paths": {
    "/stats": {
      "get": {
        "summary": "Live public numbers",
        "description": "Last 24 hours: tokens spotted, tokens in the Heat, kept out as High risk, rugs detected, median detection delay, routers, bot fee. No key.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": []
      }
    },
    "/register": {
      "get": {
        "summary": "Message to sign",
        "description": "Step 1 of 2 to get an API key without a browser: returns { message }, valid 10 minutes. No funds move.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": [],
        "parameters": [
          {
            "name": "wallet",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            }
          }
        ]
      },
      "post": {
        "summary": "Create an API key",
        "description": "Step 2: the wallet signs the message (personal_sign). Returns { key, prefix, wallet } with status 201; the key is shown once. The wallet needs 10 USDG or 0.004 ETH on Robinhood Chain. Up to 3 keys per wallet. Optional ref: a referral code whose owner earns 25% of the TRNCH fee on this key's swaps.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet",
                  "message",
                  "signature"
                ],
                "properties": {
                  "wallet": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$"
                  },
                  "message": {
                    "type": "string"
                  },
                  "signature": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string",
                    "maxLength": 24
                  },
                  "ref": {
                    "type": "string",
                    "maxLength": 40
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/heat": {
      "get": {
        "summary": "The Heat feed",
        "description": "heat: tokens screened by TIA, ranked live (opaque id, rank, heatScore, momentum, priceUsd, liquidityUsd, status, enteredHeatAt). new: just-spotted tokens, not yet screened. Pass nextSince back as since to get only new entries. Ids only work with TRNCH /quote, /build, /buy and /sell.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "nextSince of the previous call (ms or ISO)"
          }
        ]
      }
    },
    "/quote": {
      "post": {
        "summary": "Quote a swap",
        "description": "Best quote across six routers, net of the TRNCH fee. amountIn in the token's smallest unit.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tokenIn",
                  "tokenOut",
                  "amountIn"
                ],
                "properties": {
                  "tokenIn": {
                    "type": "string",
                    "description": "A 0x token address or an opaque id from GET /heat"
                  },
                  "tokenOut": {
                    "type": "string",
                    "description": "A 0x token address or an opaque id from GET /heat"
                  },
                  "amountIn": {
                    "type": "string",
                    "pattern": "^[0-9]+$"
                  },
                  "decimalsIn": {
                    "type": "integer"
                  },
                  "decimalsOut": {
                    "type": "integer"
                  },
                  "slippage": {
                    "type": "number",
                    "minimum": 0.001,
                    "maximum": 0.5
                  }
                }
              }
            }
          }
        }
      }
    },
    "/build": {
      "post": {
        "summary": "Build a swap on a given router",
        "description": "Same body as /quote plus router; returns the transaction to sign (and an approval if needed). The swap always pays the key's wallet.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "router": {
                      "type": "string"
                    },
                    "quote": {
                      "type": "object",
                      "description": "amountOut (net of the TRNCH fee), inUsd, outUsd, gasUsd, routesAsked"
                    },
                    "approval": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Send first when not null: { to, data }"
                    },
                    "tx": {
                      "type": "object",
                      "properties": {
                        "to": {
                          "type": "string",
                          "pattern": "^0x[0-9a-fA-F]{40}$"
                        },
                        "data": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        },
                        "gas": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Gas limit: the router estimate plus 30%. Send it as is."
                        }
                      }
                    },
                    "chainId": {
                      "type": "integer",
                      "const": 4663
                    },
                    "from": {
                      "type": "string",
                      "pattern": "^0x[0-9a-fA-F]{40}$"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "router",
                  "tokenIn",
                  "tokenOut",
                  "amountIn"
                ],
                "properties": {
                  "router": {
                    "type": "string",
                    "enum": [
                      "0x",
                      "kyberswap",
                      "lifi",
                      "uniswap",
                      "sushi",
                      "1inch",
                      "direct"
                    ]
                  },
                  "tokenIn": {
                    "type": "string",
                    "description": "A 0x token address or an opaque id from GET /heat"
                  },
                  "tokenOut": {
                    "type": "string",
                    "description": "A 0x token address or an opaque id from GET /heat"
                  },
                  "amountIn": {
                    "type": "string"
                  },
                  "decimalsIn": {
                    "type": "integer"
                  },
                  "decimalsOut": {
                    "type": "integer"
                  },
                  "slippage": {
                    "type": "number"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/buy": {
      "post": {
        "summary": "Buy a token",
        "description": "One call: best route across six routers, paid in USDG by default. Give tokenId or token, and amountUsd or amountIn (+ tokenIn).",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "router": {
                      "type": "string"
                    },
                    "quote": {
                      "type": "object",
                      "description": "amountOut (net of the TRNCH fee), inUsd, outUsd, gasUsd, routesAsked"
                    },
                    "approval": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Send first when not null: { to, data }"
                    },
                    "tx": {
                      "type": "object",
                      "properties": {
                        "to": {
                          "type": "string",
                          "pattern": "^0x[0-9a-fA-F]{40}$"
                        },
                        "data": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        },
                        "gas": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Gas limit: the router estimate plus 30%. Send it as is."
                        }
                      }
                    },
                    "chainId": {
                      "type": "integer",
                      "const": 4663
                    },
                    "from": {
                      "type": "string",
                      "pattern": "^0x[0-9a-fA-F]{40}$"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "string"
                  },
                  "token": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$"
                  },
                  "amountUsd": {
                    "type": "number",
                    "maximum": 50000
                  },
                  "amountIn": {
                    "type": "string"
                  },
                  "tokenIn": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$"
                  },
                  "slippageBps": {
                    "type": "integer",
                    "minimum": 10,
                    "maximum": 5000
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sell": {
      "post": {
        "summary": "Sell a token for USDG",
        "description": "One call: percent of the wallet balance or an exact amount, best route across six routers.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "router": {
                      "type": "string"
                    },
                    "quote": {
                      "type": "object",
                      "description": "amountOut (net of the TRNCH fee), inUsd, outUsd, gasUsd, routesAsked"
                    },
                    "approval": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Send first when not null: { to, data }"
                    },
                    "tx": {
                      "type": "object",
                      "properties": {
                        "to": {
                          "type": "string",
                          "pattern": "^0x[0-9a-fA-F]{40}$"
                        },
                        "data": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        },
                        "gas": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Gas limit: the router estimate plus 30%. Send it as is."
                        }
                      }
                    },
                    "chainId": {
                      "type": "integer",
                      "const": 4663
                    },
                    "from": {
                      "type": "string",
                      "pattern": "^0x[0-9a-fA-F]{40}$"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tokenId": {
                    "type": "string"
                  },
                  "token": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$"
                  },
                  "percent": {
                    "type": "number",
                    "maximum": 100
                  },
                  "amount": {
                    "type": "string"
                  },
                  "slippageBps": {
                    "type": "integer",
                    "minimum": 10,
                    "maximum": 5000
                  }
                }
              }
            }
          }
        }
      }
    },
    "/confirm": {
      "post": {
        "summary": "Report a sent swap",
        "description": "Optional: the hash of a swap you sent, so its volume counts for your TRNCH account once checked on-chain. Idempotent.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Error: { error }. 400 invalid parameters, 401 missing or invalid key, 402 wallet not funded, 409 token not tradable through TRNCH (kept out by TIA) or key limit, 429 rate or build limit (retry-after)"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "txHash"
                ],
                "properties": {
                  "txHash": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{64}$"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}