{ "openapi": "3.0.3", "info": { "version": "0.0.1", "title": "Order Book API" }, "servers": [ { "description": "Mainnet (Prod)", "url": "https://api.cow.fi/mainnet" }, { "description": "Mainnet (Staging)", "url": "https://barn.api.cow.fi/mainnet" }, { "description": "Gnosis Chain (Prod)", "url": "https://api.cow.fi/xdai" }, { "description": "Gnosis Chain (Staging)", "url": "https://barn.api.cow.fi/xdai" }, { "description": "Arbitrum One (Prod)", "url": "https://api.cow.fi/arbitrum_one" }, { "description": "Arbitrum One (Staging)", "url": "https://barn.api.cow.fi/arbitrum_one" }, { "description": "Base (Prod)", "url": "https://api.cow.fi/base" }, { "description": "Base (Staging)", "url": "https://barn.api.cow.fi/base" }, { "description": "Avalanche (Prod)", "url": "https://api.cow.fi/avalanche" }, { "description": "Avalanche (Staging)", "url": "https://barn.api.cow.fi/avalanche" }, { "description": "Polygon (Prod)", "url": "https://api.cow.fi/polygon" }, { "description": "Polygon (Staging)", "url": "https://barn.api.cow.fi/polygon" }, { "description": "Sepolia (Prod)", "url": "https://api.cow.fi/sepolia" }, { "description": "Sepolia (Staging)", "url": "https://barn.api.cow.fi/sepolia" }, { "description": "Local", "url": "http://localhost:8080" } ], "paths": { "/api/v1/orders": { "post": { "summary": "Create a new order. In order to replace an existing order with a new one, the appData must contain a [valid replacement order UID](https://github.com/cowprotocol/app-data/blob/main/src/schemas/v1.1.0.json#L62), then the indicated order is cancelled, and a new one placed.\nThis allows an old order to be cancelled AND a new order to be created in an atomic operation with a single signature.\nThis may be useful for replacing orders when on-chain prices move outside of the original order's limit price.", "responses": { "201": { "description": "Order has been accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UID" } } } }, "400": { "description": "Error during order validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPostError" } } } }, "403": { "description": "Forbidden, your account is deny-listed." }, "404": { "description": "No route was found quoting the order." }, "429": { "description": "Too many order placements." }, "500": { "description": "Error adding an order." } }, "requestBody": { "description": "The order to create.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreation" } } } } }, "delete": { "summary": "Cancel multiple orders by marking them invalid with a timestamp.", "description": "This is a *best effort* cancellation, and might not prevent solvers from settling the orders (if the order is part of an in-flight settlement transaction for example). Authentication must be provided by an [EIP-712](https://eips.ethereum.org/EIPS/eip-712) signature of an `OrderCancellations(bytes[] orderUids)` message.\n", "requestBody": { "description": "Signed `OrderCancellations`.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancellations" } } } }, "responses": { "200": { "description": "Order(s) are cancelled." }, "400": { "description": "Malformed signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancellationError" } } } }, "401": { "description": "Invalid signature." }, "404": { "description": "One or more orders were not found and no orders were cancelled." } } } }, "/api/v1/orders/{UID}": { "get": { "summary": "Get existing order from UID.", "parameters": [ { "in": "path", "name": "UID", "schema": { "$ref": "#/components/schemas/UID" }, "required": true } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "description": "Order was not found." } } }, "delete": { "deprecated": true, "summary": "Cancel an order by marking it invalid with a timestamp.", "description": "The successful deletion might not prevent solvers from settling the\norder.\n\nAuthentication must be provided by providing an\n[EIP-712](https://eips.ethereum.org/EIPS/eip-712) signature of an\n`OrderCancellation(bytes orderUid)` message.", "parameters": [ { "in": "path", "name": "UID", "schema": { "$ref": "#/components/schemas/UID" }, "required": true } ], "requestBody": { "description": "Signed `OrderCancellation`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancellation" } } } }, "responses": { "200": { "description": "Order cancelled." }, "400": { "description": "Malformed signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancellationError" } } } }, "401": { "description": "Invalid signature." }, "404": { "description": "Order was not found." } } } }, "/api/v1/orders/{UID}/status": { "get": { "summary": "Get the status of an order.", "parameters": [ { "in": "path", "name": "UID", "schema": { "$ref": "#/components/schemas/UID" }, "required": true } ], "responses": { "200": { "description": "The order status with a list of solvers that proposed solutions (if applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionOrderStatus" } } } } } } }, "/api/v1/transactions/{txHash}/orders": { "get": { "summary": "Get orders by settlement transaction hash.", "parameters": [ { "in": "path", "name": "txHash", "schema": { "$ref": "#/components/schemas/TransactionHash" }, "required": true } ], "responses": { "200": { "description": "Order(s).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } } } } }, "/api/v1/trades": { "get": { "summary": "Get existing trades.", "description": "Exactly one of `owner` or `orderUid` must be set.\n", "parameters": [ { "name": "owner", "in": "query", "schema": { "$ref": "#/components/schemas/Address" }, "required": false }, { "name": "orderUid", "in": "query", "schema": { "$ref": "#/components/schemas/UID" }, "required": false } ], "responses": { "200": { "description": "### If `owner` is specified:\n\nReturn all trades related to that `owner`.\n\n### If `orderUid` is specified:\n\nReturn all trades related to that `orderUid`. Given that an order\nmay be partially fillable, it is possible that an individual order\nmay have *multiple* trades.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } } } } } } } }, "/api/v1/auction": { "get": { "summary": "Get the current batch auction.", "description": "The current batch auction that solvers should be solving right now. This\nincludes:\n\n* A list of solvable orders. * The block on which the batch was created.\n* Prices for all tokens being traded (used for objective value\ncomputation).\n\n**Note: This endpoint is currently permissioned. Reach out in discord if\nyou need access.**", "responses": { "200": { "description": "Batch auction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Auction" } } } } } } }, "/api/v1/account/{owner}/orders": { "get": { "summary": "Get orders of one user paginated.", "description": "The orders are sorted by their creation date descending (newest orders\nfirst).\n\nTo enumerate all orders start with `offset` 0 and keep increasing the\n`offset` by the total number of returned results. When a response\ncontains less than `limit` the last page has been reached.", "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "offset", "in": "query", "description": "The pagination offset. Defaults to 0.\n", "schema": { "type": "integer" }, "required": false }, { "name": "limit", "in": "query", "description": "The pagination limit. Defaults to 10. Maximum 1000. Minimum 1.\n", "schema": { "type": "integer" }, "required": false } ], "responses": { "200": { "description": "The orders.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } }, "400": { "description": "Problem with parameters like limit being too large." } } } }, "/api/v1/token/{token}/native_price": { "get": { "summary": "Get native price for the given token.", "description": "Price is the exchange rate between the specified token and the network's\nnative currency.\n\nIt represents the amount of native token atoms needed to buy 1 atom of\nthe specified token.", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "The estimated native price.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativePriceResponse" } } } }, "400": { "description": "Error finding the price." }, "404": { "description": "No liquidity was found." }, "500": { "description": "Unexpected error." } } } }, "/api/v1/quote": { "post": { "summary": "Quote a price and fee for the specified order parameters.", "description": "Given a partial order compute the minimum fee and a price estimate for the order. Return a full order that can be used directly for signing, and with an included signature, passed directly to the order creation endpoint.\n", "requestBody": { "description": "The order parameters to compute a quote for.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderQuoteRequest" } } } }, "responses": { "200": { "description": "Quoted order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderQuoteResponse" } } } }, "400": { "description": "Error quoting order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceEstimationError" } } } }, "404": { "description": "No route was found for the specified order." }, "429": { "description": "Too many order quotes." }, "500": { "description": "Unexpected error quoting an order." } } } }, "/api/v1/solver_competition/{auction_id}": { "get": { "deprecated": true, "summary": "Get information about a solver competition.", "description": "Returns the competition information by `auction_id`.\n", "parameters": [ { "name": "auction_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Competition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolverCompetitionResponse" } } } }, "404": { "description": "No competition information available for this auction id." } } } }, "/api/v1/solver_competition/by_tx_hash/{tx_hash}": { "get": { "deprecated": true, "summary": "Get information about solver competition.", "description": "Returns the competition information by `tx_hash`.\n", "parameters": [ { "name": "tx_hash", "description": "Transaction hash in which the competition was settled.", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TransactionHash" } } ], "responses": { "200": { "description": "Competition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolverCompetitionResponse" } } } }, "404": { "description": "No competition information available for this `tx_hash`." } } } }, "/api/v1/solver_competition/latest": { "get": { "deprecated": true, "summary": "Get information about the most recent solver competition.", "description": "Returns the competition information for the last seen auction_id.\n", "responses": { "200": { "description": "Competition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolverCompetitionResponse" } } } }, "404": { "description": "No competition information available." } } } }, "/api/v2/solver_competition/{auction_id}": { "get": { "summary": "Get information about a solver competition.", "description": "Returns the competition information by `auction_id`.\n", "parameters": [ { "name": "auction_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Competition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolverCompetitionResponse" } } } }, "404": { "description": "No competition information available for this auction id." } } } }, "/api/v2/solver_competition/by_tx_hash/{tx_hash}": { "get": { "summary": "Get information about solver competition.", "description": "Returns the competition information by `tx_hash`.\n", "parameters": [ { "name": "tx_hash", "description": "Transaction hash in which the competition was settled.", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TransactionHash" } } ], "responses": { "200": { "description": "Competition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolverCompetitionResponse" } } } }, "404": { "description": "No competition information available for this `tx_hash`." } } } }, "/api/v2/solver_competition/latest": { "get": { "summary": "Get information about the most recent solver competition.", "description": "Returns the competition information for the last seen auction_id.\n", "responses": { "200": { "description": "Competition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolverCompetitionResponse" } } } }, "404": { "description": "No competition information available." } } } }, "/api/v1/version": { "get": { "summary": "Get the API's current deployed version.", "description": "Returns the git commit hash, branch name and release tag (code: https://github.com/cowprotocol/services).\n", "responses": { "200": { "description": "Version", "content": { "text/plain": {} } } } } }, "/api/v1/app_data/{app_data_hash}": { "get": { "summary": "Get the full `appData` from contract `appDataHash`.", "parameters": [ { "in": "path", "name": "app_data_hash", "schema": { "$ref": "#/components/schemas/AppDataHash" }, "required": true } ], "responses": { "200": { "description": "Full `appData`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDataObject" } } } }, "404": { "description": "No full `appData` stored for this hash." } } }, "put": { "summary": "Registers a full `appData` so it can be referenced by `appDataHash`.", "description": "Uploads a full `appData` to orderbook so that orders created with the corresponding `appDataHash` can be linked to the original full `appData`.\n", "parameters": [ { "in": "path", "name": "app_data_hash", "schema": { "$ref": "#/components/schemas/AppDataHash" }, "required": true } ], "requestBody": { "description": "The `appData` document to upload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDataObject" } } } }, "responses": { "200": { "description": "The full `appData` already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDataHash" } } } }, "201": { "description": "The full `appData` was successfully registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDataHash" } } } }, "400": { "description": "Error validating full `appData`" }, "500": { "description": "Error storing the full `appData`" } } } }, "/api/v1/app_data": { "put": { "summary": "Registers a full `appData` and returns `appDataHash`.", "description": "Uploads a full `appData` to orderbook and returns the corresponding `appDataHash`.\n", "requestBody": { "description": "The `appData` document to upload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDataObject" } } } }, "responses": { "200": { "description": "The full `appData` already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDataHash" } } } }, "201": { "description": "The full `appData` was successfully registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDataHash" } } } }, "400": { "description": "Error validating full `appData`" }, "500": { "description": "Error storing the full `appData`" } } } }, "/api/v1/users/{address}/total_surplus": { "get": { "summary": "Get the total surplus earned by the user. [UNSTABLE]", "description": "### Caution\n\nThis endpoint is under active development and should NOT be considered\nstable.", "parameters": [ { "in": "path", "name": "address", "schema": { "$ref": "#/components/schemas/Address" }, "required": true } ], "responses": { "200": { "description": "The total surplus.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotalSurplus" } } } } } } } }, "components": { "schemas": { "TransactionHash": { "description": "32 byte digest encoded as a hex with `0x` prefix.", "type": "string", "example": "0xd51f28edffcaaa76be4a22f6375ad289272c037f3cc072345676e88d92ced8b5" }, "Address": { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" }, "AppData": { "description": "The string encoding of a JSON object representing some `appData`. The\nformat of the JSON expected in the `appData` field is defined\n[here](https://github.com/cowprotocol/app-data).\n", "type": "string", "example": "{\"version\":\"0.9.0\",\"metadata\":{}}" }, "AppDataHash": { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" }, "AppDataObject": { "description": "An `appData` document that is registered with the API.", "type": "object", "properties": { "fullAppData": { "$ref": "#/components/schemas/AppData" } }, "required": [ "appData" ] }, "BigUint": { "description": "A big unsigned integer encoded in decimal.", "type": "string", "example": "1234567890" }, "CallData": { "description": "Some `calldata` sent to a contract in a transaction encoded as a hex with `0x` prefix.", "type": "string", "example": "0xca11da7a" }, "TokenAmount": { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" }, "OnchainOrderData": { "type": "object", "properties": { "sender": { "description": "If orders are placed as on-chain orders, the owner of the order might be a smart contract, but not the user placing the order. The actual user will be provided in this field.\n", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "placementError": { "description": "Describes the error, if the order placement was not successful. This could happen, for example, if the `validTo` is too high, or no valid quote was found or generated.\n", "type": "string", "enum": [ "QuoteNotFound", "ValidToTooFarInFuture", "PreValidationError" ] } }, "required": [ "sender" ] }, "EthflowData": { "description": "Provides the additional data for ethflow orders.", "type": "object", "properties": { "refundTxHash": { "description": "Specifies in which transaction the order was refunded. If\nthis field is null the order was not yet refunded.\n", "allOf": [ { "$ref": "#/components/schemas/TransactionHash" } ], "nullable": true }, "userValidTo": { "description": "Describes the `validTo` of an order ethflow order.\n\n**NOTE**: For ethflow orders, the `validTo` encoded in the smart\ncontract is `type(uint256).max`.\n", "type": "integer" } }, "required": [ "refundTxHash", "userValidTo" ] }, "OrderKind": { "description": "Is this order a buy or sell?", "type": "string", "enum": [ "buy", "sell" ] }, "OrderClass": { "description": "Order class.", "type": "string", "enum": [ "market", "limit", "liquidity" ] }, "SellTokenSource": { "description": "Where should the `sellToken` be drawn from?", "type": "string", "enum": [ "erc20", "internal", "external" ] }, "BuyTokenDestination": { "description": "Where should the `buyToken` be transferred to?", "type": "string", "enum": [ "erc20", "internal" ] }, "PriceQuality": { "description": "How good should the price estimate be?\n\nFast: The price estimate is chosen among the fastest N price estimates.\nOptimal: The price estimate is chosen among all price estimates.\nVerified: The price estimate is chosen among all verified/simulated\nprice estimates.\n\n**NOTE**: Orders are supposed to be created from `verified` or `optimal`\nprice estimates.", "type": "string", "enum": [ "fast", "optimal", "verified" ] }, "OrderStatus": { "description": "The current order status.", "type": "string", "enum": [ "presignaturePending", "open", "fulfilled", "cancelled", "expired" ] }, "OrderParameters": { "description": "Order parameters.", "type": "object", "properties": { "sellToken": { "description": "ERC-20 token to be sold.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "buyToken": { "description": "ERC-20 token to be bought.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "receiver": { "description": "An optional Ethereum address to receive the proceeds of the trade instead of the owner (i.e. the order signer).\n", "allOf": [ { "$ref": "#/components/schemas/Address" } ], "nullable": true }, "sellAmount": { "description": "Amount of `sellToken` to be sold in atoms.", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "buyAmount": { "description": "Amount of `buyToken` to be bought in atoms.", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "validTo": { "description": "Unix timestamp (`uint32`) until which the order is valid.", "type": "integer" }, "appData": { "$ref": "#/components/schemas/AppDataHash" }, "feeAmount": { "description": "sellAmount in atoms to cover network fees. Needs to be zero (and incorporated into the limit price) when placing the order", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "kind": { "description": "The kind is either a buy or sell order.", "allOf": [ { "$ref": "#/components/schemas/OrderKind" } ] }, "partiallyFillable": { "description": "Is the order fill-or-kill or partially fillable?", "type": "boolean" }, "sellTokenBalance": { "allOf": [ { "$ref": "#/components/schemas/SellTokenSource" } ], "default": "erc20" }, "buyTokenBalance": { "allOf": [ { "$ref": "#/components/schemas/BuyTokenDestination" } ], "default": "erc20" }, "signingScheme": { "allOf": [ { "$ref": "#/components/schemas/SigningScheme" } ], "default": "eip712" } }, "required": [ "sellToken", "buyToken", "sellAmount", "buyAmount", "validTo", "appData", "feeAmount", "kind", "partiallyFillable" ] }, "OrderCreation": { "description": "Data a user provides when creating a new order.", "type": "object", "properties": { "sellToken": { "description": "see `OrderParameters::sellToken`", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "buyToken": { "description": "see `OrderParameters::buyToken`", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "receiver": { "description": "see `OrderParameters::receiver`", "allOf": [ { "$ref": "#/components/schemas/Address" } ], "nullable": true }, "sellAmount": { "description": "see `OrderParameters::sellAmount`", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "buyAmount": { "description": "see `OrderParameters::buyAmount`", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "validTo": { "description": "see `OrderParameters::validTo`", "type": "integer" }, "feeAmount": { "description": "see `OrderParameters::feeAmount`", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "kind": { "description": "see `OrderParameters::kind`", "allOf": [ { "$ref": "#/components/schemas/OrderKind" } ] }, "partiallyFillable": { "description": "see `OrderParameters::partiallyFillable`", "type": "boolean" }, "sellTokenBalance": { "description": "see `OrderParameters::sellTokenBalance`", "allOf": [ { "$ref": "#/components/schemas/SellTokenSource" } ], "default": "erc20" }, "buyTokenBalance": { "description": "see `OrderParameters::buyTokenBalance`", "allOf": [ { "$ref": "#/components/schemas/BuyTokenDestination" } ], "default": "erc20" }, "signingScheme": { "$ref": "#/components/schemas/SigningScheme" }, "signature": { "$ref": "#/components/schemas/Signature" }, "from": { "description": "If set, the backend enforces that this address matches what is decoded as the *signer* of the signature. This helps catch errors with invalid signature encodings as the backend might otherwise silently work with an unexpected address that for example does not have any balance.\n", "allOf": [ { "$ref": "#/components/schemas/Address" } ], "nullable": true }, "quoteId": { "description": "Orders can optionally include a quote ID. This way the order can be linked to a quote and enable providing more metadata when analysing order slippage.\n", "type": "integer", "nullable": true }, "appData": { "description": "This field comes in two forms for backward compatibility. The hash form will eventually stop being accepted.\n", "anyOf": [ { "title": "Full App Data", "allOf": [ { "$ref": "#/components/schemas/AppData" } ], "description": "**Short**:\nIf you do not care about `appData`, set this field to `\"{}\"` and make sure that the order you signed for this request had its `appData` field set to `0xb48d38f93eaa084033fc5970bf96e559c33c4cdc07d889ab00b4d63f9590739d`.\n**Long**:\nA string encoding a JSON object like `\"{\"hello\":\"world\"}\"`.\nThis field determines the smart contract order's `appData` field, which is assumed to be set to the `keccak256` hash of the UTF-8 encoded bytes of this string. You must ensure that the signature that is part of this request indeed signed a smart contract order with the `appData` field set appropriately. If this isn't the case, signature verification will fail. For easier debugging it is recommended to additionally set the `appDataHash` field.\nThe field must be the encoding of a valid JSON object. The JSON object can contain arbitrary application specific data (JSON key values). The optional key `backend` is special. It **MUST** conform to the schema documented in `ProtocolAppData`.\nThe intended use of the other keys of the object is follow the standardized format defined [here](https://github.com/cowprotocol/app-data). Example:\n```json {\n \"version\": \"0.7.0\",\n \"appCode\": \"YOUR_APP_CODE\",\n \"metadata\": {}\n} ```\nThe total byte size of this field's UTF-8 encoded bytes is limited to 1000.", "type": "string" }, { "$ref": "#/components/schemas/AppDataHash" } ] }, "appDataHash": { "description": "May be set for debugging purposes. If set, this field is compared to what the backend internally calculates as the app data hash based on the contents of `appData`. If the hash does not match, an error is returned. If this field is set, then `appData` **MUST** be a string encoding of a JSON object.\n", "allOf": [ { "$ref": "#/components/schemas/AppDataHash" } ], "nullable": true } }, "required": [ "sellToken", "buyToken", "sellAmount", "buyAmount", "validTo", "appData", "feeAmount", "kind", "partiallyFillable", "signingScheme", "signature" ] }, "OrderMetaData": { "description": "Extra order data that is returned to users when querying orders but not provided by users when creating orders.\n", "type": "object", "properties": { "creationDate": { "description": "Creation time of the order. Encoded as ISO 8601 UTC.", "type": "string", "example": "2020-12-03T18:35:18.814523Z" }, "class": { "$ref": "#/components/schemas/OrderClass" }, "owner": { "$ref": "#/components/schemas/Address" }, "uid": { "$ref": "#/components/schemas/UID" }, "availableBalance": { "description": "Unused field that is currently always set to `null` and will be removed in the future.\n", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ], "nullable": true, "deprecated": true }, "executedSellAmount": { "description": "The total amount of `sellToken` that has been transferred from the user for this order so far.\n", "allOf": [ { "$ref": "#/components/schemas/BigUint" } ] }, "executedSellAmountBeforeFees": { "description": "The total amount of `sellToken` that has been transferred from the user for this order so far minus tokens that were transferred as part of the signed `fee` of the order. This is only relevant for old orders because now all orders have a signed `fee` of 0 and solvers compute an appropriate fee dynamically at the time of the order execution.\n", "allOf": [ { "$ref": "#/components/schemas/BigUint" } ] }, "executedBuyAmount": { "description": "The total amount of `buyToken` that has been executed for this order.\n", "allOf": [ { "$ref": "#/components/schemas/BigUint" } ] }, "executedFeeAmount": { "description": "[DEPRECATED] The total amount of the user signed `fee` that have been executed for this order. This value is only non-negative for very old orders.\n", "allOf": [ { "$ref": "#/components/schemas/BigUint" } ] }, "invalidated": { "description": "Has this order been invalidated?", "type": "boolean" }, "status": { "description": "Order status.", "allOf": [ { "$ref": "#/components/schemas/OrderStatus" } ] }, "isLiquidityOrder": { "description": "Liquidity orders are functionally the same as normal smart contract\norders but are not placed with the intent of actively getting\ntraded. Instead they facilitate the trade of normal orders by\nallowing them to be matched against liquidity orders which uses less\ngas and can have better prices than external liquidity.\n\nAs such liquidity orders will only be used in order to improve\nsettlement of normal orders. They should not be expected to be\ntraded otherwise and should not expect to get surplus.", "type": "boolean" }, "ethflowData": { "allOf": [ { "$ref": "#/components/schemas/EthflowData" } ] }, "onchainUser": { "description": "This represents the actual trader of an on-chain order.\n### ethflow orders\nIn this case, the `owner` would be the `EthFlow` contract and *not* the actual trader.\n", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "onchainOrderData": { "description": "There is some data only available for orders that are placed on-chain. This data can be found in this object.\n", "allOf": [ { "$ref": "#/components/schemas/OnchainOrderData" } ] }, "executedFee": { "description": "Total fee charged for execution of the order. Contains network fee and protocol fees. This takes into account the historic static fee signed by the user and the new dynamic fee computed by solvers.\n", "allOf": [ { "$ref": "#/components/schemas/BigUint" } ], "nullable": false }, "executedFeeToken": { "description": "Token the executed fee was captured in.", "allOf": [ { "$ref": "#/components/schemas/Address" } ], "nullable": false }, "fullAppData": { "description": "Full `appData`, which the contract-level `appData` is a hash of. See `OrderCreation` for more information.\n", "type": "string", "nullable": true } }, "required": [ "creationDate", "class", "owner", "uid", "executedSellAmount", "executedSellAmountBeforeFees", "executedBuyAmount", "executedFeeAmount", "invalidated", "status" ] }, "Order": { "allOf": [ { "$ref": "#/components/schemas/OrderCreation" }, { "$ref": "#/components/schemas/OrderMetaData" } ] }, "AuctionOrder": { "description": "A solvable order included in the current batch auction. Contains the data forwarded to solvers for solving.\n", "type": "object", "properties": { "uid": { "$ref": "#/components/schemas/UID" }, "sellToken": { "description": "see `OrderParameters::sellToken`", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "buyToken": { "description": "see `OrderParameters::buyToken`", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "sellAmount": { "description": "see `OrderParameters::sellAmount`", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "buyAmount": { "description": "see `OrderParameters::buyAmount`", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "created": { "description": "Creation time of the order. Denominated in epoch seconds.", "type": "string", "example": "123456" }, "validTo": { "description": "see `OrderParameters::validTo`", "type": "integer" }, "kind": { "description": "see `OrderParameters::kind`", "allOf": [ { "$ref": "#/components/schemas/OrderKind" } ] }, "receiver": { "description": "see `OrderParameters::receiver`", "allOf": [ { "$ref": "#/components/schemas/Address" } ], "nullable": true }, "owner": { "$ref": "#/components/schemas/Address" }, "partiallyFillable": { "description": "see `OrderParameters::partiallyFillable`", "type": "boolean" }, "executed": { "description": "Currently executed amount of sell/buy token, depending on the order kind.\n", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "preInteractions": { "description": "The pre-interactions that need to be executed before the first execution of the order.\n", "type": "array", "items": { "$ref": "#/components/schemas/InteractionData" } }, "postInteractions": { "description": "The post-interactions that need to be executed after the execution of the order.\n", "type": "array", "items": { "$ref": "#/components/schemas/InteractionData" } }, "sellTokenBalance": { "description": "see `OrderParameters::sellTokenBalance`", "allOf": [ { "$ref": "#/components/schemas/SellTokenSource" } ], "default": "erc20" }, "buyTokenBalance": { "description": "see `OrderParameters::buyTokenBalance`", "allOf": [ { "$ref": "#/components/schemas/BuyTokenDestination" } ], "default": "erc20" }, "class": { "$ref": "#/components/schemas/OrderClass" }, "appData": { "$ref": "#/components/schemas/AppDataHash" }, "signature": { "$ref": "#/components/schemas/Signature" }, "protocolFees": { "description": "The fee policies that are used to compute the protocol fees for this order.\n", "type": "array", "items": { "$ref": "#/components/schemas/FeePolicy" } }, "quote": { "description": "A winning quote.\n", "allOf": [ { "$ref": "#/components/schemas/Quote" } ] } }, "required": [ "uid", "sellToken", "buyToken", "sellAmount", "buyAmount", "created", "validTo", "kind", "receiver", "owner", "partiallyFillable", "executed", "preInteractions", "postInteractions", "sellTokenBalance", "buyTokenBalance", "class", "appData", "signature", "protocolFees" ] }, "Auction": { "description": "A batch auction for solving.\n", "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the auction. Increment whenever the backend creates a new auction.\n" }, "block": { "type": "integer", "description": "The block number for the auction. Orders and prices are guaranteed to be valid on this block. Proposed settlements should be valid for this block as well.\n" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/AuctionOrder" }, "description": "The solvable orders included in the auction.\n" }, "prices": { "$ref": "#/components/schemas/AuctionPrices" }, "surplusCapturingJitOrderOwners": { "type": "array", "items": { "$ref": "#/components/schemas/Address" }, "description": "List of addresses on whose surplus will count towards the objective value of their solution (unlike other orders that were created by the solver).\n" } } }, "CompetitionAuction": { "description": "The components that describe a batch auction for the solver competition.\n", "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/UID" }, "description": "The UIDs of the orders included in the auction.\n" }, "prices": { "$ref": "#/components/schemas/AuctionPrices" } } }, "ExecutedAmounts": { "type": "object", "properties": { "sell": { "$ref": "#/components/schemas/BigUint" }, "buy": { "$ref": "#/components/schemas/BigUint" } }, "required": [ "sell", "buy" ] }, "CompetitionOrderStatus": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "open", "scheduled", "active", "solved", "executing", "traded", "cancelled" ] }, "value": { "description": "A list of solvers who participated in the latest competition, sorted\nby score in ascending order, where the last element is the winner.\n\nThe presence of executed amounts defines whether the solver provided\na solution for the desired order.", "type": "array", "items": { "type": "object", "properties": { "solver": { "type": "string", "description": "Name of the solver." }, "executedAmounts": { "$ref": "#/components/schemas/ExecutedAmounts" } }, "required": [ "solver" ] } } }, "required": [ "type" ] }, "AuctionPrices": { "description": "The reference prices for all traded tokens in the auction as a mapping from token addresses to a price denominated in native token (i.e. 1e18 represents a token that trades one to one with the native token). These prices are used for solution competition for computing surplus and converting fees to native token.\n", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BigUint" } }, "OrderCancellations": { "description": "EIP-712 signature of struct OrderCancellations { orderUid: bytes[] } from the order's owner.\n", "type": "object", "properties": { "orderUids": { "type": "array", "description": "UIDs of orders to cancel.", "items": { "$ref": "#/components/schemas/UID" } }, "signature": { "description": "`OrderCancellation` signed by the owner.", "allOf": [ { "$ref": "#/components/schemas/EcdsaSignature" } ] }, "signingScheme": { "allOf": [ { "$ref": "#/components/schemas/EcdsaSigningScheme" } ] } }, "required": [ "signature", "signingScheme" ] }, "OrderCancellation": { "description": "[EIP-712](https://eips.ethereum.org/EIPS/eip-712) signature of struct\n`OrderCancellation(bytes orderUid)` from the order's owner.\n", "type": "object", "properties": { "signature": { "description": "OrderCancellation signed by owner", "allOf": [ { "$ref": "#/components/schemas/EcdsaSignature" } ] }, "signingScheme": { "$ref": "#/components/schemas/EcdsaSigningScheme" } }, "required": [ "signature", "signingScheme" ] }, "Trade": { "description": "Trade data such as executed amounts, fees, `orderUid` and `block` number.\n", "type": "object", "properties": { "blockNumber": { "description": "Block in which trade occurred.", "type": "integer" }, "logIndex": { "description": "Index in which transaction was included in block.", "type": "integer" }, "orderUid": { "description": "UID of the order matched by this trade.", "allOf": [ { "$ref": "#/components/schemas/UID" } ] }, "owner": { "description": "Address of trader.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "sellToken": { "description": "Address of token sold.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "buyToken": { "description": "Address of token bought.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "sellAmount": { "description": "Total amount of `sellToken` that has been executed for this trade (including fees).", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "sellAmountBeforeFees": { "description": "The total amount of `sellToken` that has been executed for this order without fees.", "allOf": [ { "$ref": "#/components/schemas/BigUint" } ] }, "buyAmount": { "description": "Total amount of `buyToken` received in this trade.", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "txHash": { "description": "Transaction hash of the corresponding settlement transaction containing the trade (if available).", "allOf": [ { "$ref": "#/components/schemas/TransactionHash" } ], "nullable": true }, "executedProtocolFees": { "description": "Executed protocol fees for this trade, together with the fee policies used. Listed in the order they got applied.\n", "type": "array", "items": { "$ref": "#/components/schemas/ExecutedProtocolFee" } } }, "required": [ "blockNumber", "logIndex", "orderUid", "owner", "sellToken", "buyToken", "sellAmount", "sellAmountBeforeFees", "buyAmount", "txHash" ] }, "UID": { "description": "Unique identifier for the order: 56 bytes encoded as hex with `0x`\nprefix.\n\nBytes 0..32 are the order digest, bytes 30..52 the owner address and\nbytes 52..56 the expiry (`validTo`) as a `uint32` unix epoch timestamp.", "type": "string", "example": "0xff2e2e54d178997f173266817c1e9ed6fee1a1aae4b43971c53b543cffcc2969845c6f5599fbb25dbdd1b9b013daf85c03f3c63763e4bc4a" }, "SigningScheme": { "description": "How was the order signed?", "type": "string", "enum": [ "eip712", "ethsign", "presign", "eip1271" ] }, "EcdsaSigningScheme": { "description": "How was the order signed?", "type": "string", "enum": [ "eip712", "ethsign" ] }, "Signature": { "description": "A signature.", "oneOf": [ { "$ref": "#/components/schemas/EcdsaSignature" }, { "$ref": "#/components/schemas/PreSignature" } ] }, "EcdsaSignature": { "description": "65 bytes encoded as hex with `0x` prefix. `r || s || v` from the spec.", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" }, "PreSignature": { "description": "Empty signature bytes. Used for \"presign\" signatures.", "type": "string", "example": "0x" }, "OrderPostError": { "type": "object", "properties": { "errorType": { "type": "string", "enum": [ "DuplicatedOrder", "QuoteNotFound", "QuoteNotVerified", "InvalidQuote", "MissingFrom", "WrongOwner", "InvalidEip1271Signature", "InsufficientBalance", "InsufficientAllowance", "InvalidSignature", "SellAmountOverflow", "TransferSimulationFailed", "ZeroAmount", "IncompatibleSigningScheme", "TooManyLimitOrders", "TooMuchGas", "UnsupportedBuyTokenDestination", "UnsupportedSellTokenSource", "UnsupportedOrderType", "InsufficientValidTo", "ExcessiveValidTo", "InvalidNativeSellToken", "SameBuyAndSellToken", "UnsupportedToken", "InvalidAppData", "AppDataHashMismatch", "AppdataFromMismatch", "OldOrderActivelyBidOn" ] }, "description": { "type": "string" } }, "required": [ "errorType", "description" ] }, "OrderCancellationError": { "type": "object", "properties": { "errorType": { "type": "string", "enum": [ "InvalidSignature", "WrongOwner", "OrderNotFound", "AlreadyCancelled", "OrderFullyExecuted", "OrderExpired", "OnChainOrder" ] }, "description": { "type": "string" } }, "required": [ "errorType", "description" ] }, "PriceEstimationError": { "type": "object", "properties": { "errorType": { "type": "string", "enum": [ "QuoteNotVerified", "UnsupportedToken", "ZeroAmount", "UnsupportedOrderType" ] }, "description": { "type": "string" } }, "required": [ "errorType", "description" ] }, "OrderQuoteSide": { "description": "The buy or sell side when quoting an order.", "oneOf": [ { "type": "object", "description": "Quote a sell order given the final total `sellAmount` including fees.", "properties": { "kind": { "allOf": [ { "$ref": "#/components/schemas/OrderQuoteSideKindSell" } ] }, "sellAmountBeforeFee": { "description": "The total amount that is available for the order. From this value, the fee is deducted and the buy amount is calculated.\n", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] } }, "required": [ "kind", "sellAmountBeforeFee" ] }, { "type": "object", "description": "Quote a sell order given the `sellAmount`.", "properties": { "kind": { "allOf": [ { "$ref": "#/components/schemas/OrderQuoteSideKindSell" } ] }, "sellAmountAfterFee": { "description": "The `sellAmount` for the order.", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] } }, "required": [ "kind", "sellAmountAfterFee" ] }, { "type": "object", "description": "Quote a buy order given an exact `buyAmount`.", "properties": { "kind": { "allOf": [ { "$ref": "#/components/schemas/OrderQuoteSideKindBuy" } ] }, "buyAmountAfterFee": { "description": "The `buyAmount` for the order.", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] } }, "required": [ "kind", "buyAmountAfterFee" ] } ] }, "OrderQuoteSideKindSell": { "type": "string", "enum": [ "sell" ] }, "OrderQuoteSideKindBuy": { "type": "string", "enum": [ "buy" ] }, "OrderQuoteValidity": { "description": "The validity for the order.", "oneOf": [ { "type": "object", "description": "Absolute validity.", "properties": { "validTo": { "description": "Unix timestamp (`uint32`) until which the order is valid.", "type": "integer" } } }, { "type": "object", "description": "Relative validity", "properties": { "validFor": { "description": "Number (`uint32`) of seconds that the order should be valid for.", "type": "integer" } } } ] }, "OrderQuoteRequest": { "description": "Request fee and price quote.", "allOf": [ { "$ref": "#/components/schemas/OrderQuoteSide" }, { "$ref": "#/components/schemas/OrderQuoteValidity" }, { "type": "object", "properties": { "sellToken": { "description": "ERC-20 token to be sold", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "buyToken": { "description": "ERC-20 token to be bought", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "receiver": { "description": "An optional address to receive the proceeds of the trade instead of the\n`owner` (i.e. the order signer).\n", "allOf": [ { "$ref": "#/components/schemas/Address" } ], "nullable": true }, "appData": { "description": "AppData which will be assigned to the order.\n\nExpects either a string JSON doc as defined on\n[AppData](https://github.com/cowprotocol/app-data) or a hex\nencoded string for backwards compatibility.\n\nWhen the first format is used, it's possible to provide the\nderived appDataHash field.", "oneOf": [ { "$ref": "#/components/schemas/AppData" }, { "$ref": "#/components/schemas/AppDataHash" } ] }, "appDataHash": { "description": "The hash of the stringified JSON appData doc.\n\nIf present, `appData` field must be set with the aforementioned\ndata where this hash is derived from.\n\nIn case they differ, the call will fail.", "anyOf": [ { "$ref": "#/components/schemas/AppDataHash" } ] }, "sellTokenBalance": { "allOf": [ { "$ref": "#/components/schemas/SellTokenSource" } ], "default": "erc20" }, "buyTokenBalance": { "allOf": [ { "$ref": "#/components/schemas/BuyTokenDestination" } ], "default": "erc20" }, "from": { "$ref": "#/components/schemas/Address" }, "priceQuality": { "allOf": [ { "$ref": "#/components/schemas/PriceQuality" } ], "default": "verified" }, "signingScheme": { "allOf": [ { "$ref": "#/components/schemas/SigningScheme" } ], "default": "eip712" }, "onchainOrder": { "description": "Flag to signal whether the order is intended for on-chain order placement. Only valid for non ECDSA-signed orders.\"\n", "default": false }, "timeout": { "type": "integer", "description": "User provided timeout in milliseconds. Can only be used to reduce the response time for quote requests if the default is too slow as values greater than the default will be capped to the default. Note that reducing the timeout can result in worse quotes because the reduced timeout might be too slow for some price estimators.\n" } }, "required": [ "sellToken", "buyToken", "from" ] } ] }, "OrderQuoteResponse": { "description": "An order quoted by the backend that can be directly signed and\nsubmitted to the order creation backend.\n", "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/OrderParameters" }, "from": { "$ref": "#/components/schemas/Address" }, "expiration": { "description": "Expiration date of the offered fee. Order service might not accept\nthe fee after this expiration date. Encoded as ISO 8601 UTC.\n", "type": "string", "example": "1985-03-10T18:35:18.814523Z" }, "id": { "description": "Quote ID linked to a quote to enable providing more metadata when analysing order slippage.\n", "type": "integer" }, "verified": { "description": "Whether it was possible to verify that the quoted amounts are accurate using a simulation.\n", "type": "boolean" } }, "required": [ "quote", "expiration", "verified" ] }, "SolverCompetitionResponse": { "description": "The settlements submitted by every solver for a specific auction.\nThe `auctionId` corresponds to the id external solvers are provided\nwith.\n", "type": "object", "properties": { "auctionId": { "type": "integer", "description": "The ID of the auction the competition info is for." }, "auctionStartBlock": { "type": "integer", "description": "Block that the auction started on." }, "transactionHashes": { "type": "array", "description": "The hashes of the transactions for the winning solutions of this competition.\n", "items": { "$ref": "#/components/schemas/TransactionHash" } }, "referenceScores": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BigUint" }, "description": "The reference scores for each winning solver according to [CIP-67](https://forum.cow.fi/t/cip-67-moving-from-batch-auction-to-the-fair-combinatorial-auction/2967) (if available).\n" }, "auction": { "$ref": "#/components/schemas/CompetitionAuction" }, "solutions": { "type": "array", "description": "Maps from solver name to object describing that solver's settlement.", "items": { "$ref": "#/components/schemas/SolverSettlement" } } } }, "SolverSettlement": { "type": "object", "properties": { "ranking": { "type": "number", "description": "Which position the solution achieved in the total ranking of the competition." }, "solverAddress": { "type": "string", "description": "The address used by the solver to execute the settlement on-chain.\n\nThis field is missing for old settlements, the zero address has been\nused instead." }, "score": { "allOf": [ { "$ref": "#/components/schemas/BigUint" } ], "description": "The score of the current auction as defined in [CIP-20](https://snapshot.org/#/cow.eth/proposal/0x2d3f9bd1ea72dca84b03e97dda3efc1f4a42a772c54bd2037e8b62e7d09a491f).\n" }, "referenceScore": { "allOf": [ { "$ref": "#/components/schemas/BigUint" } ], "description": "The reference score as defined in [CIP-67](https://forum.cow.fi/t/cip-67-moving-from-batch-auction-to-the-fair-combinatorial-auction/2967) (if available).\n", "nullable": true }, "txHash": { "allOf": [ { "$ref": "#/components/schemas/TransactionHash" } ], "description": "Transaction in which the solution was executed onchain (if available).\n", "nullable": true }, "clearingPrices": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BigUint" }, "description": "The prices of tokens for settled user orders as passed to the settlement contract.\n" }, "orders": { "type": "array", "description": "Touched orders.", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/UID" }, "sellAmount": { "$ref": "#/components/schemas/BigUint" }, "buyAmount": { "$ref": "#/components/schemas/BigUint" } } } }, "isWinner": { "type": "boolean", "description": "whether the solution is a winner (received the right to get executed) or not" }, "filteredOut": { "type": "boolean", "description": "whether the solution was filtered out according to the rules of [CIP-67](https://forum.cow.fi/t/cip-67-moving-from-batch-auction-to-the-fair-combinatorial-auction/2967)." } } }, "NativePriceResponse": { "description": "The estimated native price for the token\n", "type": "object", "properties": { "price": { "type": "number", "description": "Estimated price of the token." } } }, "TotalSurplus": { "description": "The total surplus.\n", "type": "object", "properties": { "totalSurplus": { "type": "string", "description": "The total surplus." } } }, "InteractionData": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/Address" }, "value": { "$ref": "#/components/schemas/TokenAmount" }, "call_data": { "type": "array", "items": { "$ref": "#/components/schemas/CallData" }, "description": "The call data to be used for the interaction." } } }, "Quote": { "description": "A calculated order quote.\n", "type": "object", "properties": { "sellAmount": { "description": "The amount of the sell token.", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "buyAmount": { "description": "The amount of the buy token.", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] }, "fee": { "description": "The amount that needs to be paid, denominated in the sell token.", "allOf": [ { "$ref": "#/components/schemas/TokenAmount" } ] } } }, "Surplus": { "description": "The protocol fee is taken as a percent of the surplus.", "type": "object", "properties": { "factor": { "type": "number", "minimum": 0, "maximum": 1, "exclusiveMaximum": true }, "maxVolumeFactor": { "type": "number", "minimum": 0, "maximum": 1, "exclusiveMaximum": true } }, "required": [ "factor", "maxVolumeFactor" ] }, "Volume": { "description": "The protocol fee is taken as a percent of the order volume.", "type": "object", "properties": { "factor": { "type": "number", "minimum": 0, "maximum": 1, "exclusiveMaximum": true } }, "required": [ "factor" ] }, "PriceImprovement": { "description": "The protocol fee is taken as a percent of the order price improvement which is a difference between the executed price and the best quote.", "type": "object", "properties": { "factor": { "type": "number", "minimum": 0, "maximum": 1, "exclusiveMaximum": true }, "maxVolumeFactor": { "type": "number", "minimum": 0, "maximum": 1, "exclusiveMaximum": true }, "quote": { "description": "The best quote received.", "allOf": [ { "$ref": "#/components/schemas/Quote" } ] } }, "required": [ "factor", "maxVolumeFactor", "quote" ] }, "FeePolicy": { "description": "Defines the ways to calculate the protocol fee.", "oneOf": [ { "$ref": "#/components/schemas/Surplus" }, { "$ref": "#/components/schemas/Volume" }, { "$ref": "#/components/schemas/PriceImprovement" } ] }, "ExecutedProtocolFee": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/FeePolicy" }, "amount": { "allOf": [ { "description": "Fee amount taken" }, { "$ref": "#/components/schemas/TokenAmount" } ] }, "token": { "allOf": [ { "description": "The token in which the fee is taken" }, { "$ref": "#/components/schemas/Address" } ] } } } } } }