{
  "openapi": "3.1.0",
  "info": {
    "title": "Allways App API",
    "version": "1.0.0",
    "description": "Swap any listed asset for any other across chains. Flow: find asset ids, quote, open a swap, send the deposit, poll the swap. No account or API key. Amounts are exact decimal strings in whole units of the asset.",
    "contact": { "email": "support@all-ways.io" }
  },
  "servers": [{ "url": "https://all-ways.io" }],
  "paths": {
    "/api/assets": {
      "get": {
        "operationId": "findAssets",
        "summary": "Find asset ids by words, best match first.",
        "description": "Every word must match the symbol, name or network. Example: \"usdc arbitrum\".",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching assets.",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetMatch" } }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "operationId": "getCatalog",
        "summary": "Every listed network and asset. Large; prefer /api/assets.",
        "responses": {
          "200": {
            "description": "The listed catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["networks", "assets"],
                  "properties": {
                    "networks": { "type": "array", "items": { "type": "object" } },
                    "assets": { "type": "array", "items": { "type": "object" } },
                    "updatedAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/quotes": {
      "post": {
        "operationId": "getQuote",
        "summary": "Quote the best route for a pair.",
        "description": "side=send: amount is what you send. side=receive: amount is what you want; amountIn is the send amount that gets it. Open the swap with amountIn as amount and the route's amountOut as expectedOut.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteInput" } } }
        },
        "responses": {
          "200": {
            "description": "The best routes; best is null when no route covers the amount (see min/max).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteView" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/swaps": {
      "post": {
        "operationId": "openSwap",
        "summary": "Open a swap and get the deposit address.",
        "description": "Send exactly amountIn of the from asset to deposit (with its memo, if any) before expiresAt, once. deposit.tx (EVM) and deposit.uri are that payment ready-made; on Solana and for TAO, POST /api/swaps/{id}/deposit-tx builds it. A 409 rate_changed carries the new amountOut; re-confirm and retry with it.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "8 to 128 printable characters. Retrying with the same key and body returns the same swap.",
            "schema": { "type": "string", "minLength": 8, "maxLength": 128 }
          },
          {
            "name": "x-allways-channel",
            "in": "header",
            "required": false,
            "description": "Analytics source. Use web for browser clients; MCP supplies mcp. Missing or unknown values are recorded as api.",
            "schema": { "type": "string", "enum": ["web", "api", "mcp"] }
          }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenSwapInput" } } }
        },
        "responses": {
          "200": {
            "description": "The opened swap.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapView" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/swaps/{id}": {
      "get": {
        "operationId": "getSwap",
        "summary": "Read a swap's status. Poll until status is terminal.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "The swap.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapView" } } }
          },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/swaps/{id}/report": {
      "post": {
        "operationId": "reportSwapProblem",
        "summary": "Report a problem with a swap so the team can investigate it.",
        "description": "The team receives the report with the swap's diagnosis. The first report opens a case; repeats add to that case, up to five entries. A successful response has reported=true.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/ReportInput" } }
          }
        },
        "responses": {
          "200": {
            "description": "The swap with reported=true.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapView" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/swaps/{id}/deposit-tx": {
      "post": {
        "operationId": "buildDepositTx",
        "summary": "Solana and TAO only: build the unsigned deposit of a swap in awaiting_deposit.",
        "description": "The reply moves exactly amountIn of the from asset to the deposit address, and nothing else. Nothing is signed or sent here. Send it once. Solana (reply `transaction`): a SOL transfer, or an SPL transferChecked after an idempotent create of the deposit's token account, with a memo instruction when the deposit has a memo. `from` pays the fee and signs. Sign and send it within about a minute; if it expired unsent, build a new one. TAO (reply `call` and `node`): the unsigned Balances.transfer_keep_alive call. `call.callHex` is the SCALE-encoded call, not a signed extrinsic: the paying coldkey signs it (it adds nonce, era and tip) and submits it to `node`. `from` and `version` are not read. The same payment by hand: `btcli tx transfer --dest <deposit.address> --amount-tao <amountIn>`. 409: the swap is not awaiting a deposit or its address expired, do not send. 400: the swap is not paid from Solana or in TAO, `from` is not a Solana address, or `version` is not legacy or 0. 422: the amount does not fit one Solana transfer, or a TAO deposit needs a memo; do not send, open a new swap. 503: the chain cannot be read; try again shortly.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string",
                    "description": "Solana: required, the address that pays and signs. TAO: not read."
                  },
                  "version": {
                    "enum": ["legacy", 0],
                    "default": "legacy",
                    "description": "Solana only: the transaction format. Most wallets send both; send 0 for a wallet that only sends version 0 transactions, such as Trust Wallet."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The unsigned deposit: `transaction` for Solana, `call` and `node` for TAO.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositTxView" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/auth/wallet/challenge": {
      "post": {
        "operationId": "startReferralSignIn",
        "tags": ["Referrals"],
        "summary": "Start referrer sign-in with a Bittensor coldkey. Sign the returned message with it within 5 minutes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["address"],
                "properties": { "address": { "type": "string", "description": "Coldkey, ss58." } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The message to sign.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/WalletChallenge" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/auth/wallet/verify": {
      "post": {
        "operationId": "finishReferralSignIn",
        "tags": ["Referrals"],
        "summary": "Send the signed message. With bearer: true, returns a 30-day token for the Authorization header instead of a cookie.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["address", "nonce", "signature"],
                "properties": {
                  "address": { "type": "string" },
                  "nonce": { "type": "string" },
                  "signature": { "type": "string", "description": "Hex signature by the coldkey." },
                  "bearer": {
                    "type": "boolean",
                    "description": "Return a token instead of setting a cookie."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The account, and the token when bearer is true.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BearerSession" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/auth/signout": {
      "post": {
        "operationId": "signOut",
        "tags": ["Referrals"],
        "summary": "End the session.",
        "security": [{ "bearer": [] }],
        "responses": { "204": { "description": "Signed out." } }
      }
    },
    "/api/me/referral-codes": {
      "get": {
        "operationId": "getMyReferralCodes",
        "tags": ["Referrals"],
        "summary": "Your codes with swaps, volume and users on each.",
        "security": [{ "bearer": [] }],
        "responses": {
          "200": {
            "description": "Your codes.",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MyCode" } }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      },
      "post": {
        "operationId": "createReferralCode",
        "tags": ["Referrals"],
        "summary": "Make a random referral code. Custom codes are set up by the Allways team.",
        "security": [{ "bearer": [] }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": { "label": { "type": "string", "description": "A private note." } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "All your codes.",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MyCode" } }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/referral-codes/{code}": {
      "get": {
        "operationId": "checkReferralCode",
        "tags": ["Referrals"],
        "summary": "Whether a code is live.",
        "parameters": [{ "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "The check.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["valid"],
                  "properties": { "valid": { "type": "boolean" } }
                }
              }
            }
          }
        }
      }
    },
    "/api/referrals/leaderboard": {
      "get": {
        "operationId": "getReferralLeaderboard",
        "tags": ["Referrals"],
        "summary": "Public referrer ranking, with what each was paid.",
        "parameters": [
          {
            "name": "window",
            "in": "query",
            "schema": { "type": "string", "enum": ["7d", "30d", "all"], "default": "all" }
          }
        ],
        "responses": {
          "200": {
            "description": "The ranking.",
            "content": {
              "application/json": { "schema": { "type": "array", "items": { "type": "object" } } }
            }
          }
        }
      }
    },
    "/api/referrals/payouts": {
      "get": {
        "operationId": "getReferralPayouts",
        "tags": ["Referrals"],
        "summary": "Public log of referral payouts.",
        "responses": {
          "200": {
            "description": "The payouts.",
            "content": {
              "application/json": { "schema": { "type": "array", "items": { "type": "object" } } }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Error": {
        "description": "A failure with a stable code and a message to show.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      }
    },
    "schemas": {
      "Decimal": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "examples": ["0.015"] },
      "AssetMatch": {
        "type": "object",
        "required": ["id", "symbol", "name", "network", "decimals"],
        "properties": {
          "id": { "type": "string", "description": "Pass as from or to." },
          "symbol": { "type": "string" },
          "name": { "type": "string" },
          "network": { "type": "string", "description": "The network's name, e.g. \"Arbitrum\"." },
          "decimals": { "type": "integer" }
        }
      },
      "Destination": {
        "type": "object",
        "required": ["address"],
        "properties": {
          "address": { "type": "string" },
          "memo": { "type": "string", "description": "Memo or destination tag, on networks that use one." }
        }
      },
      "EvmTx": {
        "type": "object",
        "description": "An unsigned EVM transaction. Hand it to a wallet unchanged; the wallet adds the sender, nonce and gas.",
        "required": ["chainId", "to", "value", "data"],
        "properties": {
          "chainId": { "type": "integer", "description": "The chain of the from asset." },
          "to": {
            "type": "string",
            "description": "The deposit address, or for a token its contract (the deposit address is inside data)."
          },
          "value": { "type": "string", "description": "Wei, as a 0x hex quantity. \"0x0\" for a token." },
          "data": {
            "type": "string",
            "description": "\"0x\" for the chain's coin; for a token, ERC-20 transfer(deposit address, amountIn in atomic units)."
          }
        }
      },
      "DepositView": {
        "type": "object",
        "required": ["address"],
        "properties": {
          "address": { "type": "string" },
          "memo": { "type": "string", "description": "Memo or destination tag. The transfer must carry it." },
          "uri": {
            "type": "string",
            "description": "The payment of exactly amountIn as a link: BIP21 (Bitcoin), Solana Pay (Solana), EIP-681 (EVM). Only while status is awaiting_deposit and before expiresAt. Absent on networks with no standard link, or when the link cannot carry the memo."
          },
          "tx": {
            "$ref": "#/components/schemas/EvmTx",
            "description": "EVM only: the payment of exactly amountIn as an unsigned transaction. Only while status is awaiting_deposit and before expiresAt."
          }
        }
      },
      "DepositTxView": {
        "type": "object",
        "description": "One of two shapes, by the chain of the swap's from asset. Solana: `transaction` alone. TAO: `call` and `node`.",
        "oneOf": [{ "required": ["transaction"] }, { "required": ["call", "node"] }],
        "properties": {
          "transaction": {
            "type": "string",
            "description": "Solana: base64 of an unsigned Solana transaction with a fresh blockhash, in the asked version (legacy by default)."
          },
          "call": {
            "$ref": "#/components/schemas/UnsignedCall",
            "description": "TAO: the unsigned Balances.transfer_keep_alive of exactly amountIn to the deposit address."
          },
          "node": {
            "type": "string",
            "description": "TAO: a Bittensor node (WebSocket URL) to read the nonce from and submit the signed call to."
          }
        }
      },
      "UnsignedCall": {
        "type": "object",
        "description": "A Bittensor call with no signature. The signer wraps it in an extrinsic with its own nonce, era and tip.",
        "required": ["method", "args", "callHex"],
        "properties": {
          "method": {
            "type": "string",
            "description": "Pallet and call as polkadot-js names them. For a TAO deposit: balances.transferKeepAlive, the Balances.transfer_keep_alive call."
          },
          "args": {
            "type": "object",
            "additionalProperties": { "type": "string" },
            "description": "The decoded arguments, to check before signing. For a TAO deposit: `dest` is the deposit address (ss58) and `value` is amountIn in rao (1 TAO = 1,000,000,000 rao)."
          },
          "callHex": {
            "type": "string",
            "description": "The SCALE-encoded call as 0x hex. Not a signed extrinsic, and not a signing payload."
          }
        }
      },
      "QuoteInput": {
        "type": "object",
        "required": ["from", "to", "amount"],
        "properties": {
          "from": { "type": "string", "description": "Asset id to send." },
          "to": { "type": "string", "description": "Asset id to receive." },
          "amount": { "$ref": "#/components/schemas/Decimal" },
          "side": { "type": "string", "enum": ["send", "receive"], "default": "send" },
          "withMemo": {
            "type": "boolean",
            "description": "Set when the payout or refund carries a memo: only routes that pass a memo on are quoted."
          }
        }
      },
      "RouteQuote": {
        "type": "object",
        "required": ["providerId", "providerName", "amountOut", "needsRefundAddress"],
        "properties": {
          "providerId": { "type": "string" },
          "providerName": { "type": "string", "description": "Public display name for the selected route." },
          "amountOut": { "$ref": "#/components/schemas/Decimal" },
          "min": { "$ref": "#/components/schemas/Decimal" },
          "max": { "$ref": "#/components/schemas/Decimal" },
          "needsRefundAddress": { "type": "boolean" }
        }
      },
      "MemoRule": {
        "type": "object",
        "required": ["memo"],
        "properties": {
          "memo": { "type": "string", "enum": ["none", "optional", "required"] },
          "memoLabel": { "type": "string" }
        }
      },
      "QuoteView": {
        "type": "object",
        "required": ["amountIn", "best"],
        "properties": {
          "amountIn": { "$ref": "#/components/schemas/Decimal" },
          "best": { "oneOf": [{ "$ref": "#/components/schemas/RouteQuote" }, { "type": "null" }] },
          "min": { "$ref": "#/components/schemas/Decimal" },
          "max": { "$ref": "#/components/schemas/Decimal" }
        }
      },
      "OpenSwapInput": {
        "type": "object",
        "required": ["from", "to", "amount", "expectedOut", "payout"],
        "properties": {
          "from": { "type": "string" },
          "to": { "type": "string" },
          "amount": {
            "$ref": "#/components/schemas/Decimal",
            "description": "The send amount: the quote's amountIn."
          },
          "providerId": {
            "type": "string",
            "description": "Optional. Omit it and the server opens the best route that pays at least expectedOut and needs no wallet signature."
          },
          "expectedOut": {
            "$ref": "#/components/schemas/Decimal",
            "description": "The route's amountOut; the swap never opens for less."
          },
          "payout": { "$ref": "#/components/schemas/Destination" },
          "refund": {
            "$ref": "#/components/schemas/Destination",
            "description": "Required when the route's needsRefundAddress is true: every route but a native one signed in a wallet. Set here only; it cannot be set or changed later."
          },
          "referralCode": { "type": "string" }
        }
      },
      "ReportInput": {
        "type": "object",
        "required": ["category", "message"],
        "properties": {
          "category": {
            "type": "string",
            "enum": ["not_received", "wrong_amount", "refund", "slow", "stats_wrong", "other"],
            "description": "What went wrong."
          },
          "message": {
            "type": "string",
            "minLength": 10,
            "maxLength": 500,
            "description": "What happened."
          },
          "contact": {
            "type": "string",
            "format": "email",
            "description": "Optional reply email for the team handling the report."
          },
          "depositTx": {
            "type": "string",
            "maxLength": 200,
            "description": "Only with not_received: the deposit transaction you sent. With another category it is a 400."
          },
          "amountDelivered": {
            "type": "string",
            "maxLength": 40,
            "description": "Only with wrong_amount: the amount that arrived, as a positive decimal. With another category it is a 400."
          }
        }
      },
      "SwapView": {
        "type": "object",
        "required": [
          "id",
          "status",
          "from",
          "to",
          "amountIn",
          "amountOutQuoted",
          "providerName",
          "payout",
          "notices",
          "reported",
          "createdAt",
          "legs"
        ],
        "properties": {
          "id": { "type": "string" },
          "status": {
            "type": "string",
            "enum": [
              "creating",
              "create_unknown",
              "awaiting_deposit",
              "confirming",
              "exchanging",
              "refund_needed",
              "finished",
              "refunded",
              "failed",
              "expired"
            ],
            "description": "Terminal: finished, refunded, failed, expired."
          },
          "from": { "type": "string" },
          "to": { "type": "string" },
          "amountIn": { "$ref": "#/components/schemas/Decimal" },
          "amountOutQuoted": { "$ref": "#/components/schemas/Decimal" },
          "providerName": {
            "type": "string",
            "description": "Public display name only; provider order ids and client references are never exposed."
          },
          "amountReceived": { "$ref": "#/components/schemas/Decimal" },
          "amountDelivered": { "$ref": "#/components/schemas/Decimal" },
          "deposit": {
            "$ref": "#/components/schemas/DepositView",
            "description": "Where to send amountIn, once. Present only while the swap can be funded."
          },
          "expiresAt": { "type": "string", "format": "date-time" },
          "payout": { "$ref": "#/components/schemas/Destination" },
          "refund": { "$ref": "#/components/schemas/Destination" },
          "payoutTx": { "type": "string" },
          "refundTx": { "type": "string" },
          "notices": {
            "type": "array",
            "items": { "type": "string", "enum": ["under_deposit", "stuck", "aml_hold", "price_moved"] }
          },
          "reported": {
            "type": "boolean",
            "description": "True while this swap has an open user report case."
          },
          "createdAt": { "type": "string", "format": "date-time" },
          "legs": { "type": "array", "items": { "type": "object" } },
          "referral": {
            "type": "string",
            "enum": ["applied", "ignored"],
            "description": "Open only, when a referralCode was sent: whether it was recorded."
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "rate_changed",
              "out_of_bounds",
              "unavailable",
              "invalid_address",
              "invalid_memo",
              "blocked",
              "not_found",
              "bad_request",
              "locked"
            ]
          },
          "message": { "type": "string" },
          "amountOut": {
            "$ref": "#/components/schemas/Decimal",
            "description": "rate_changed only: the new amount."
          }
        }
      },
      "WalletChallenge": {
        "type": "object",
        "required": ["nonce", "message"],
        "properties": {
          "nonce": { "type": "string" },
          "message": { "type": "string", "description": "Sign this exact text." }
        }
      },
      "BearerSession": {
        "type": "object",
        "required": ["coldkey", "createdAt"],
        "properties": {
          "coldkey": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" },
          "token": { "type": "string", "description": "Send as Authorization: Bearer <token>." }
        }
      },
      "MyCode": {
        "type": "object",
        "required": ["code", "createdAt", "swaps", "volumeUsd", "users"],
        "properties": {
          "code": { "type": "string" },
          "label": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "revokedAt": { "type": ["string", "null"], "format": "date-time" },
          "swaps": { "type": "integer" },
          "volumeUsd": { "type": "number" },
          "users": { "type": "integer" }
        }
      }
    },
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "The token from finishReferralSignIn with bearer: true."
      }
    }
  }
}
