{
  "name": "Polkaswap Agent Trading API",
  "version": "v1",
  "runtime": "browser",
  "hosting": "static-ipfs",
  "global": "window.PolkaswapAgent",
  "readyEvent": "polkaswap-agent-ready",
  "docs": "./polkaswap-agent.md",
  "types": "./polkaswap-agent.d.ts",
  "schema": "./polkaswap-agent.schema.json",
  "examples": "./polkaswap-agent.examples.json",
  "errorCatalog": "./polkaswap-agent.errors.json",
  "client": "./polkaswap-agent-client.js",
  "repositoryDocs": "https://github.com/sora-xor/polkaswap-exchange-web/blob/develop/docs/agent-trading.md",
  "breadcrumbs": {
    "llms": "../llms.txt",
    "agents": "../agents.txt",
    "agentInstructions": "../AGENTS.md",
    "robots": "../robots.txt",
    "htmlHead": [
      "link[rel=\"help\"][type=\"application/json\"][href$=\"polkaswap-agent.json\"]",
      "meta[name=\"polkaswap-agent-api\"]",
      "meta[name=\"ai-agent-api\"]"
    ]
  },
  "developerTools": {
    "playground": "../agent-playground.html",
    "exampleRunner": "https://github.com/sora-xor/polkaswap-exchange-web/tree/develop/examples/agent-runner",
    "exampleRunnerCommand": "yarn agent:runner"
  },
  "learningPath": [
    "Require version v1.",
    "Open the app in a browser with ?polkaswap-agent=1 before the hash route, then wait for window.PolkaswapAgent or polkaswap-agent-ready.",
    "Call ready({ requireNode: true }) before quotes, prepares, or execution.",
    "Use refreshWallets, walletAccounts, and connectWallet to select a signer through the page wallet system.",
    "Resolve asset symbols to addresses once, then use addresses for repeated execution.",
    "Use quote* methods for read-only exploration and prepare* methods before every signature.",
    "Execute only when canExecute is true and runner policy accepts warnings.",
    "Pass the returned intentId and a stable clientOrderId to every execute* call.",
    "Persist exportState() after signer handoff and recover uncertain submissions before retrying."
  ],
  "stateChangingPattern": {
    "prepareFirst": true,
    "executeRequiresIntentId": true,
    "executeShouldUseClientOrderId": true,
    "recoveryBeforeRetry": true,
    "privateKeysAcceptedByPage": false
  },
  "runnerChecklist": [
    "capabilities().version is v1",
    "ready({ requireNode: true }) succeeded",
    "wallet account is selected when the operation requires signing",
    "assets are canonical addresses",
    "prepare* returned canExecute true",
    "critical warnings are rejected unless the runner policy explicitly allows them",
    "execute request includes intentId",
    "execute request includes a stable clientOrderId",
    "exportState() is persisted after signer handoff"
  ],
  "capabilities": [
    "status",
    "wallet-connect",
    "wallet-accounts",
    "asset-discovery",
    "asset-resolution",
    "swap-quote",
    "swap-prepare",
    "swap-risk-assessment",
    "swap-execute",
    "transfer-prepare",
    "transfer-execute",
    "pool-info",
    "liquidity-positions",
    "liquidity-add-quote",
    "liquidity-add-prepare",
    "liquidity-add-execute",
    "liquidity-remove-quote",
    "liquidity-remove-prepare",
    "liquidity-remove-execute",
    "max-amounts",
    "transaction-status",
    "transaction-lookup",
    "transaction-recovery",
    "transaction-wait",
    "transaction-history",
    "transaction-subscriptions",
    "transaction-indexer-subscriptions",
    "status-subscriptions",
    "portable-agent-state"
  ],
  "methods": [
    "capabilities",
    "ready",
    "status",
    "refreshWallets",
    "walletAccounts",
    "connectWallet",
    "assets",
    "resolveAsset",
    "commonAssets",
    "quoteSwap",
    "prepareSwap",
    "assessSwap",
    "executeSwap",
    "prepareTransfer",
    "executeTransfer",
    "poolInfo",
    "liquidityPositions",
    "quoteAddLiquidity",
    "prepareAddLiquidity",
    "executeAddLiquidity",
    "quoteRemoveLiquidity",
    "prepareRemoveLiquidity",
    "executeRemoveLiquidity",
    "maxTransferAmount",
    "maxSwapInput",
    "maxAddLiquidity",
    "maxRemoveLiquidity",
    "transactionStatus",
    "lookupTransaction",
    "recoverTransaction",
    "waitForTransaction",
    "recentTransactions",
    "subscribeTransactions",
    "subscribeStatus",
    "exportState",
    "importState",
    "clearState"
  ],
  "methodMetadata": {
    "stateChanging": ["executeSwap", "executeTransfer", "executeAddLiquidity", "executeRemoveLiquidity"],
    "requiresWallet": [
      "executeSwap",
      "executeTransfer",
      "liquidityPositions",
      "executeAddLiquidity",
      "executeRemoveLiquidity",
      "maxTransferAmount",
      "maxSwapInput",
      "maxAddLiquidity",
      "maxRemoveLiquidity"
    ],
    "requiresUserApproval": ["connectWallet"],
    "acceptsIntentId": ["executeSwap", "executeTransfer", "executeAddLiquidity", "executeRemoveLiquidity"],
    "acceptsClientOrderId": ["executeSwap", "executeTransfer", "executeAddLiquidity", "executeRemoveLiquidity"],
    "quoteOnly": ["quoteSwap", "quoteAddLiquidity", "quoteRemoveLiquidity"],
    "prepareBeforeExecute": {
      "executeSwap": "prepareSwap",
      "executeTransfer": "prepareTransfer",
      "executeAddLiquidity": "prepareAddLiquidity",
      "executeRemoveLiquidity": "prepareRemoveLiquidity"
    },
    "subscriptions": ["subscribeTransactions", "subscribeStatus"]
  },
  "defaults": {
    "side": "input",
    "dexId": "best",
    "allowPoolCreation": false,
    "slippageTolerance": "current app setting"
  },
  "limits": {
    "slippageTolerance": { "min": "0.01", "max": "10", "unit": "percent" },
    "percent": { "min": "0.01", "max": "100", "unit": "percent" },
    "defaultReadyTimeoutMs": 30000,
    "defaultQuoteTimeoutMs": 15000
  },
  "security": {
    "middleware": false,
    "samePageOnly": true,
    "postMessage": false,
    "urlCommands": false,
    "custody": "caller-provided-wallet",
    "signing": "existing-page-wallet-flow"
  },
  "intentProtection": {
    "quoteMethodsReturnIntentId": true,
    "prepareMethodsReturnIntentId": true,
    "executeMethodsAcceptIntentId": true,
    "executeMethodsAcceptClientOrderId": true,
    "staleIntentError": "INTENT_MISMATCH"
  },
  "errors": [
    "AGENT_API_UNAVAILABLE",
    "ASSET_AMBIGUOUS",
    "ASSET_NOT_FOUND",
    "INVALID_AMOUNT",
    "INVALID_AGENT_STATE",
    "INVALID_ASSET_REF",
    "INVALID_CLIENT_ORDER_ID",
    "INVALID_DEX_ID",
    "IDEMPOTENCY_CONFLICT",
    "INTENT_MISMATCH",
    "INVALID_LIQUIDITY_SOURCE",
    "INVALID_PERCENT",
    "INVALID_POOL_PAIR",
    "INVALID_RECIPIENT",
    "INVALID_SLIPPAGE",
    "INVALID_SUBSCRIPTION_SOURCE",
    "INVALID_SWAP_SIDE",
    "INVALID_TRANSACTION_ID",
    "INVALID_WALLET_SOURCE",
    "NODE_NOT_READY",
    "PATH_UNAVAILABLE",
    "POOL_UNAVAILABLE",
    "QUOTE_TIMEOUT",
    "SIGNING_CANCELLED",
    "WALLET_ACCOUNT_NOT_FOUND",
    "WALLET_ACCOUNT_REQUIRED",
    "WALLET_NOT_CONNECTED",
    "WALLET_NOT_FOUND"
  ]
}