{
  "openapi": "3.1.0",
  "info": {
    "title": "Hyperliquid API",
    "version": "1.0.0",
    "description": "The exchange API for Hyperliquid, by Quicknode. Trade perpetuals, spot, HIP-3 builder markets (assets like `xyz:AAPL`) and HIP-4 outcome markets (assets like `#10`) with a readable build/sign/send REST flow. No API key. Non-custodial: you sign the returned hash with your own key and post it back.\n\nBuild calls (no `signature` field) return the exact action and hash to sign. Send calls (with `nonce` and `signature`) are verified and forwarded to Hyperliquid. Machine-readable docs: https://hyperliquidapi.com/llms-full.txt",
    "contact": { "url": "https://hyperliquidapi.com/docs" }
  },
  "servers": [{ "url": "https://send.hyperliquidapi.com" }],
  "paths": {
    "/exchange": {
      "post": {
        "summary": "Build or send an exchange action",
        "description": "One endpoint, two phases. **Build**: POST an action without a signature; the response includes the exact `action`, `nonce` and `hash` to sign (builder fee injected, optional `priorityFee` encoded into `action.grouping`). **Send**: POST the returned `action` plus `nonce` and `signature`; the request is verified and forwarded to Hyperliquid. Action types include `order`, `cancel`, `modify`, `closePosition`, `approveBuilderFee`, `outcomeSplit` and other outcome helpers, `cDeposit`, and user-signed actions.",
        "operationId": "exchange",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ExchangeRequest" },
              "examples": {
                "buildMarketOrder": {
                  "summary": "Build a market order (no signature)",
                  "value": {
                    "action": {
                      "type": "order",
                      "orders": [
                        { "asset": "BTC", "side": "buy", "size": "0.001", "tif": "market" }
                      ]
                    }
                  }
                },
                "buildLimitOrderWithPriority": {
                  "summary": "Build an IOC order with a priority fee",
                  "value": {
                    "priorityFee": 10000,
                    "action": {
                      "type": "order",
                      "orders": [
                        { "asset": "BTC", "side": "buy", "price": "100000", "size": "0.001", "tif": "ioc" }
                      ]
                    }
                  }
                },
                "buildHip4Order": {
                  "summary": "Build a HIP-4 outcome order. The # alias encodes outcomeId × 10 + side (0 = Yes, 1 = No): #100 is outcome 10's Yes side. 10 USDC minimum, no priorityFee.",
                  "value": {
                    "action": {
                      "type": "order",
                      "orders": [
                        { "asset": "#100", "side": "buy", "price": "0.63411", "size": "16", "tif": "ioc" }
                      ]
                    }
                  }
                },
                "send": {
                  "summary": "Send a built action with its signature",
                  "value": {
                    "action": { "type": "order", "orders": ["… exactly as returned by the build call …"] },
                    "nonce": 1719000000000,
                    "signature": { "r": "0x…", "s": "0x…", "v": 27 }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Build response (hash to sign) or send response (exchange result).",
            "content": {
              "application/json": {
                "examples": {
                  "build": {
                    "summary": "Build response (market orders also carry appliedSlippage)",
                    "value": {
                      "hash": "0x9f2c…",
                      "nonce": 1719000000000,
                      "action": { "type": "order", "orders": ["…"] },
                      "isSpot": false,
                      "builderFee": "0.04%",
                      "builderFeeRaw": 40,
                      "builder": "0x…",
                      "appliedSlippage": "3.0%",
                      "appliedSlippageRaw": 0.03,
                      "nextStep": "Sign the hash with your private key (ECDSA), then POST /exchange with action, nonce, and signature (r, s, v)."
                    }
                  },
                  "send": {
                    "summary": "Send response (exchangeResponse is Hyperliquid's, verbatim)",
                    "value": {
                      "success": true,
                      "user": "0x…",
                      "exchangeResponse": { "status": "ok", "response": { "type": "order", "data": { "statuses": [{ "filled": { "totalSz": "0.001", "avgPx": "62600", "oid": 123456789 } }] } } },
                      "orders": ["…"]
                    }
                  }
                }
              }
            }
          },
          "403": { "$ref": "#/components/responses/NotApproved" },
          "422": { "$ref": "#/components/responses/InvalidParams" }
        }
      }
    },
    "/approval": {
      "get": {
        "summary": "Check builder-fee approval for a user",
        "operationId": "checkApproval",
        "parameters": [{ "$ref": "#/components/parameters/User" }],
        "responses": {
          "200": {
            "description": "Approval status and trading capability.",
            "content": {
              "application/json": {
                "example": {
                  "approved": true,
                  "maxFeeRate": "1%",
                  "maxFeeRaw": 1000,
                  "canTradePerps": true,
                  "canTradeSpot": true,
                  "feeBreakdown": { "perps": "0.04%", "spot": "0.05%" }
                }
              }
            }
          }
        }
      }
    },
    "/openOrders": {
      "post": {
        "summary": "List a user's open orders with ready-made cancel actions",
        "operationId": "openOrders",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "example": { "user": "0xYOUR_ADDRESS" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Open orders plus cancelActions.all and cancelActions.byAsset.",
            "content": { "application/json": { "example": { "orders": ["…"], "count": 2, "cancelActions": { "all": "…", "byAsset": "…" } } } }
          }
        }
      }
    },
    "/orderStatus": {
      "post": {
        "summary": "Status of one order by oid or cloid",
        "operationId": "orderStatus",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "example": { "user": "0xYOUR_ADDRESS", "oid": 123456789 } } }
        },
        "responses": {
          "200": {
            "description": "Order status with a plain-language explanation.",
            "content": { "application/json": { "example": { "status": "filled", "explanation": "…", "coin": "BTC", "asset": "BTC", "isSpot": false, "order": "…", "statusTimestamp": 1719000000000 } } }
          }
        }
      }
    },
    "/preflight": {
      "post": {
        "summary": "Validate an order without placing it",
        "operationId": "preflight",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "example": { "action": { "type": "order", "orders": [{ "asset": "BTC", "side": "buy", "size": "0.001", "tif": "market" }] } } } }
        },
        "responses": {
          "200": {
            "description": "Validity, estimated fees and asset context.",
            "content": { "application/json": { "example": { "valid": true, "errors": [], "assetInfo": "…", "estimatedFee": "…", "isSpot": false } } }
          }
        }
      }
    },
    "/markets": {
      "get": {
        "summary": "All tradeable markets: perps, spot, HIP-3 and HIP-4",
        "operationId": "listMarkets",
        "responses": {
          "200": {
            "description": "Market lists grouped by family.",
            "content": { "application/json": { "example": { "perps": ["…"], "spot": ["…"], "hip3": ["…"], "hip4": ["…"] } } }
          }
        }
      }
    },
    "/outcomes": {
      "get": {
        "summary": "Live HIP-4 outcome markets (USDC-settled)",
        "operationId": "listOutcomes",
        "responses": {
          "200": {
            "description": "Outcome markets with questions, encoding and available actions. Geo-restricted jurisdictions receive a 403.",
            "content": { "application/json": { "example": { "quoteToken": "USDC", "outcomes": ["…"], "questions": ["…"], "encoding": "…", "actions": ["…"] } } }
          }
        }
      }
    },
    "/outcomes/balances": {
      "get": {
        "summary": "USDC plus Yes/No balances for one outcome",
        "operationId": "outcomeBalances",
        "parameters": [
          { "$ref": "#/components/parameters/User" },
          { "name": "outcome", "in": "query", "required": true, "schema": { "type": "integer" }, "example": 10 }
        ],
        "responses": {
          "200": {
            "description": "Balances for the outcome's quote and both sides.",
            "content": { "application/json": { "example": { "user": "0x…", "outcome": 10, "quote": "125.00", "yes": "16", "no": "0", "actions": ["…"] } } }
          }
        }
      }
    },
    "/dexes": {
      "get": {
        "summary": "HIP-3 builder-deployed dexes",
        "operationId": "listDexes",
        "responses": {
          "200": {
            "description": "Dex names and indices.",
            "content": { "application/json": { "example": [{ "name": "xyz", "index": 1 }] } }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "User": {
        "name": "user",
        "in": "query",
        "required": true,
        "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
        "example": "0xYOUR_ADDRESS"
      }
    },
    "schemas": {
      "ExchangeRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": {
            "type": "object",
            "description": "The Hyperliquid action. For orders: { type: \"order\", orders: [{ asset, side, price?, size, tif }] }. asset accepts tickers (\"BTC\"), HIP-3 ids (\"xyz:AAPL\") and HIP-4 aliases (\"#10\")."
          },
          "priorityFee": {
            "type": "integer",
            "maximum": 80000,
            "description": "Optional IOC-only priority rate p (10000 = 1 bp). Encoded as action.grouping {\"p\": priorityFee} before hashing. Paid from undelegated staking HYPE. Not supported on HIP-4 # markets."
          },
          "vaultAddress": { "type": "string", "description": "Optional vault address." },
          "slippage": { "type": "number", "description": "Market-order slippage tolerance, 0.001 to 0.1 (default 0.03)." },
          "nonce": { "type": "integer", "description": "Send phase only: the nonce from the build response." },
          "signature": {
            "type": "object",
            "description": "Send phase only: EIP-712 signature of the build hash.",
            "properties": {
              "r": { "type": "string" },
              "s": { "type": "string" },
              "v": { "type": "integer", "enum": [27, 28] }
            }
          }
        }
      }
    },
    "responses": {
      "NotApproved": {
        "description": "Builder fee not approved. The body includes approvalRequired with the exact hash and typedData to sign, plus nextStep.",
        "content": {
          "application/json": {
            "example": {
              "error": "NOT_APPROVED",
              "message": "User 0x… has not approved builder 0x…",
              "guidance": "Builder fee not approved…",
              "approvalRequired": { "hash": "0xabc…", "nonce": 1708000000000, "maxFeeRate": "1%", "approveUrl": "/approve", "nextStep": "Sign the hash, then POST /exchange with action, nonce, and signature" }
            }
          }
        }
      },
      "InvalidParams": {
        "description": "Invalid parameters, builder mismatch, bad signature, or an exchange rejection. Every error carries error, message and guidance.",
        "content": {
          "application/json": {
            "example": { "error": "INVALID_PARAMS", "message": "…", "guidance": "…" }
          }
        }
      }
    }
  }
}