{
  "openapi": "3.1.0",
  "info": {
    "title": "HekaSwap Agent API",
    "version": "1.0.0",
    "summary": "Privacy-focused swap quotes and x402-paid order creation for automated agents.",
    "description": "Quotes are free. Order creation requires an Idempotency-Key and can be gated by x402 payment when enabled.",
    "x-guidance": "Use GET /api/agent/v1/routes to inspect allowed routes and caps. Create preview quotes for free with POST /api/agent/v1/quotes. Create orders only after the receive wallet is known. POST /api/agent/v1/orders is the x402-paid endpoint and costs $0.01 in Base USDC when payment is enabled. Do not send swap funds until the order response returns depositInstructions."
  },
  "servers": [
    {
      "url": "https://www.hekaswap.com"
    }
  ],
  "tags": [
    {
      "name": "Agent API"
    }
  ],
  "paths": {
    "/api/agent/v1/routes": {
      "get": {
        "tags": [
          "Agent API"
        ],
        "summary": "List agent routes and payment metadata",
        "responses": {
          "200": {
            "description": "Allowed routes and public x402 configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoutesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/quotes": {
      "post": {
        "tags": [
          "Agent API"
        ],
        "summary": "Create a free quote",
        "description": "Set previewOnly=true to price a route before the user or agent supplies the receive wallet.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              },
              "examples": {
                "eth_ethereum_to_xmr": {
                  "value": {
                    "fromAsset": "ETH",
                    "fromNetwork": "Ethereum",
                    "toAsset": "XMR",
                    "toNetwork": "Monero",
                    "amount": "0.25",
                    "previewOnly": true,
                    "clientReferenceId": "agent-job-123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/orders": {
      "post": {
        "tags": [
          "Agent API"
        ],
        "summary": "Create an idempotent swap order",
        "description": "Creates provider deposit instructions from a quote. This endpoint is the x402-paid resource when x402 is enabled.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "amount": "0.01",
            "currency": "USD"
          },
          "protocols": [
            {
              "x402": {
                "scheme": "exact",
                "network": "eip155:8453",
                "payTo": "0x50e9216ffe691faf66725871c427bb3e51c58b75",
                "header": "PAYMENT-SIGNATURE"
              }
            }
          ]
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderRequest"
              },
              "examples": {
                "createOrder": {
                  "value": {
                    "quoteId": "q_REPLACE",
                    "destinationAddress": "REPLACE_WITH_RECEIVE_WALLET",
                    "refundAddress": "REPLACE_WITH_SOURCE_CHAIN_REFUND_ADDRESS",
                    "clientReferenceId": "agent-job-123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created order with deposit instructions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required."
          }
        }
      }
    },
    "/api/agent/v1/orders/{orderId}": {
      "get": {
        "tags": [
          "Agent API"
        ],
        "summary": "Get order status",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current order snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 8
        },
        "description": "Stable client-generated key for safe retries."
      }
    },
    "schemas": {
      "RoutesResponse": {
        "type": "object",
        "required": [
          "agent",
          "routes"
        ],
        "properties": {
          "agent": {
            "$ref": "#/components/schemas/Agent"
          },
          "routes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Route"
            }
          }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "allowedRouteIds": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "eth_ethereum_to_xmr"
              ]
            }
          },
          "requireIdempotencyKey": {
            "type": "boolean"
          },
          "payment": {
            "$ref": "#/components/schemas/Payment"
          }
        }
      },
      "Payment": {
        "type": "object",
        "properties": {
          "protocol": {
            "type": "string",
            "const": "x402"
          },
          "requiredForOrders": {
            "type": "boolean"
          },
          "configured": {
            "type": "boolean"
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": {
                  "type": "string"
                },
                "price": {
                  "type": "string"
                },
                "network": {
                  "type": "string"
                },
                "payTo": {
                  "type": "string"
                }
              }
            }
          },
          "description": {
            "type": "string"
          }
        }
      },
      "Route": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "eth_ethereum_to_xmr"
            ]
          },
          "fromAsset": {
            "type": "string"
          },
          "fromNetwork": {
            "type": "string"
          },
          "toAsset": {
            "type": "string"
          },
          "toNetwork": {
            "type": "string"
          },
          "minAmount": {
            "type": "string"
          },
          "maxAmount": {
            "type": "string"
          }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": [
          "fromAsset",
          "fromNetwork",
          "toAsset",
          "toNetwork",
          "amount"
        ],
        "properties": {
          "fromAsset": {
            "type": "string"
          },
          "fromNetwork": {
            "type": "string"
          },
          "toAsset": {
            "type": "string"
          },
          "toNetwork": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "destinationAddress": {
            "type": "string",
            "description": "Receive wallet. Required unless previewOnly=true."
          },
          "previewOnly": {
            "type": "boolean"
          },
          "dryRun": {
            "type": "boolean"
          },
          "clientReferenceId": {
            "type": "string"
          },
          "agentJobId": {
            "type": "string"
          }
        }
      },
      "Quote": {
        "type": "object",
        "properties": {
          "quoteId": {
            "type": "string"
          },
          "amountIn": {
            "type": "string"
          },
          "amountOut": {
            "type": "string"
          },
          "minAmount": {
            "type": "string"
          },
          "maxAmount": {
            "type": "string"
          },
          "destinationAddress": {
            "type": [
              "string",
              "null"
            ]
          },
          "previewOnly": {
            "type": "boolean"
          },
          "quoteMode": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "bestRoute": {
            "type": "object"
          },
          "alternativeRoutes": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "pricing": {
            "type": [
              "object",
              "null"
            ]
          }
        }
      },
      "OrderRequest": {
        "type": "object",
        "required": [
          "quoteId",
          "destinationAddress"
        ],
        "properties": {
          "quoteId": {
            "type": "string"
          },
          "destinationAddress": {
            "type": "string"
          },
          "refundAddress": {
            "type": "string",
            "description": "Optional source-chain refund address."
          },
          "providerId": {
            "type": "string"
          },
          "clientReferenceId": {
            "type": "string"
          },
          "agentJobId": {
            "type": "string"
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "string"
          },
          "quoteId": {
            "type": "string"
          },
          "amountIn": {
            "type": "string"
          },
          "amountOut": {
            "type": [
              "string",
              "null"
            ]
          },
          "destinationAddress": {
            "type": "string"
          },
          "refundAddress": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "failureCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "selectedRoute": {
            "type": [
              "object",
              "null"
            ]
          },
          "pricing": {
            "type": [
              "object",
              "null"
            ]
          },
          "depositInstructions": {
            "type": [
              "object",
              "null"
            ]
          },
          "timeline": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  },
  "x-hekaswap": {
    "agentId": "heka-agent-api",
    "payment": {
      "protocol": "x402",
      "requiredForOrders": true,
      "configured": true,
      "accepts": [
        {
          "scheme": "exact",
          "price": "$0.01",
          "network": "eip155:8453",
          "payTo": "0x50e9216ffe691faf66725871c427bb3e51c58b75"
        }
      ],
      "facilitatorUrl": "https://x402.dexter.cash",
      "facilitatorMode": "remote",
      "description": "Create a HekaSwap privacy-focused swap order for an automated agent."
    },
    "allowedRouteIds": [
      "eth_ethereum_to_xmr"
    ]
  }
}