{
  "openapi": "3.1.0",
  "info": {
    "title": "VeTrade Swap Planning API",
    "version": "2.0.0",
    "description": "Machine-native VeChain swap and trading planning endpoint for AI agents and developer tooling. VeTrade is a VeChain DEX aggregator for swap, trading, quote, and limit-order workflows. The API supports quote-only planning and wallet-bound bundle preparation, but it does not sign or execute transactions. Authentication is not required during the current public beta."
  },
  "servers": [
    {
      "url": "https://vetrade.vet",
      "description": "Production"
    }
  ],
  "paths": {
    "/v2/swap-plans": {
      "post": {
        "operationId": "createSwapPlan",
        "summary": "Create a machine-native VeChain swap plan",
        "description": "Return routing, warnings, and optionally a wallet-bound clause bundle for swapping or trading tokens on VeChain through VeTrade.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "https://vetrade.vet/schemas/swap-plan-request.schema.json"
              },
              "examples": {
                "quoteOnly": {
                  "summary": "Quote-only planning request",
                  "value": {
                    "mode": "quote_only",
                    "inputToken": "0x0000000000000000000000000000000000000000",
                    "outputToken": "0x45429a2255e7248e57fce99e7239aed3f84b7a53",
                    "amountIn": "1000000000000000000",
                    "slippageBps": 100,
                    "routing": {
                      "maxHops": 3,
                      "maxSplits": 2
                    }
                  }
                },
                "walletBound": {
                  "summary": "Wallet-bound request with simulation",
                  "value": {
                    "mode": "wallet_bound",
                    "inputToken": "0x0000000000000000000000000000000000000000",
                    "outputToken": "0x45429a2255e7248e57fce99e7239aed3f84b7a53",
                    "amountIn": "1000000000000000000",
                    "recipient": "0x1111111111111111111111111111111111111111",
                    "slippageBps": 100,
                    "include": {
                      "simulation": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Swap plan created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "https://vetrade.vet/schemas/swap-plan-response.schema.json"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "502": {
            "description": "Upstream router or node failure"
          }
        }
      },
      "get": {
        "operationId": "describeSwapPlansEndpoint",
        "summary": "Return usage guidance for the swap planning endpoint",
        "responses": {
          "200": {
            "description": "Machine-readable guidance for clients that want to discover the POST contract before sending a body",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "apiVersion",
                    "endpoint",
                    "message",
                    "supportedMethods",
                    "post",
                    "docsUrl"
                  ],
                  "properties": {
                    "apiVersion": {
                      "type": "string",
                      "const": "v2"
                    },
                    "endpoint": {
                      "type": "string",
                      "const": "/v2/swap-plans"
                    },
                    "message": {
                      "type": "string"
                    },
                    "supportedMethods": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "post": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "contentType",
                        "requiredFields",
                        "example"
                      ],
                      "properties": {
                        "contentType": {
                          "type": "string",
                          "const": "application/json"
                        },
                        "requiredFields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "example": {
                          "$ref": "https://vetrade.vet/schemas/swap-plan-request.schema.json"
                        }
                      }
                    },
                    "docsUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                },
                "examples": {
                  "usageGuide": {
                    "summary": "Usage guidance for clients that probed the endpoint with GET",
                    "value": {
                      "apiVersion": "v2",
                      "endpoint": "/v2/swap-plans",
                      "message": "Use POST /v2/swap-plans with a JSON body to request a swap plan.",
                      "supportedMethods": [
                        "GET",
                        "POST",
                        "OPTIONS"
                      ],
                      "post": {
                        "contentType": "application/json",
                        "requiredFields": [
                          "mode",
                          "inputToken",
                          "outputToken",
                          "amountIn"
                        ],
                        "example": {
                          "mode": "quote_only",
                          "inputToken": "0x0000000000000000000000000000000000000000",
                          "outputToken": "0x45429a2255e7248e57fce99e7239aed3f84b7a53",
                          "amountIn": "1000000000000000000"
                        }
                      },
                      "docsUrl": "https://vetrade.vet/developers/ai/swap-plans"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}