Trade

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cow-protocol/json-schema/cow-protocol-trade-schema.json",
  "title": "Trade",
  "description": "Trade data such as executed amounts, fees, `orderUid` and `block` number.\n",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/orderbook.yml#/components/schemas/Trade",
  "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": "#/$defs/UID"
        }
      ]
    },
    "owner": {
      "description": "Address of trader.",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        }
      ]
    },
    "sellToken": {
      "description": "Address of token sold.",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        }
      ]
    },
    "buyToken": {
      "description": "Address of token bought.",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        }
      ]
    },
    "sellAmount": {
      "description": "Total amount of `sellToken` that has been executed for this trade (including fees).",
      "allOf": [
        {
          "$ref": "#/$defs/TokenAmount"
        }
      ]
    },
    "sellAmountBeforeFees": {
      "description": "The total amount of `sellToken` that has been executed for this order without fees.",
      "allOf": [
        {
          "$ref": "#/$defs/BigUint"
        }
      ]
    },
    "buyAmount": {
      "description": "Total amount of `buyToken` received in this trade.",
      "allOf": [
        {
          "$ref": "#/$defs/TokenAmount"
        }
      ]
    },
    "txHash": {
      "description": "Transaction hash of the corresponding settlement transaction containing the trade (if available).",
      "allOf": [
        {
          "$ref": "#/$defs/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": "#/$defs/ExecutedProtocolFee"
      }
    },
    "gasCost": {
      "description": "Estimated gas cost attributed to this trade, in native token wei: the settlement's gas cost split equally between the user trades it settled, not weighted by the gas each one consumed. Omitted until the settlement has been attributed, shortly after it is indexed, and permanently if it predates this being recorded. `0` for a JIT order that only provided liquidity.\n",
      "allOf": [
        {
          "$ref": "#/$defs/BigUint"
        }
      ]
    },
    "penaltyCapNative": {
      "description": "Cap on the penalty the winning solver could incur for not executing the order in the auction this trade settled, denominated in native token wei. Absent when the auction had a pre CIP-87 global penalty cap.",
      "allOf": [
        {
          "$ref": "#/$defs/BigUint"
        }
      ],
      "nullable": true
    }
  },
  "required": [
    "blockNumber",
    "logIndex",
    "orderUid",
    "owner",
    "sellToken",
    "buyToken",
    "sellAmount",
    "sellAmountBeforeFees",
    "buyAmount",
    "txHash"
  ],
  "$defs": {
    "Address": {
      "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.",
      "type": "string"
    },
    "BigUint": {
      "description": "A big unsigned integer encoded in decimal.",
      "type": "string"
    },
    "ExecutedProtocolFee": {
      "type": "object",
      "properties": {
        "policy": {
          "$ref": "#/$defs/FeePolicy"
        },
        "amount": {
          "allOf": [
            {
              "description": "Fee amount taken"
            },
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        },
        "token": {
          "allOf": [
            {
              "description": "The token in which the fee is taken"
            },
            {
              "$ref": "#/$defs/Address"
            }
          ]
        }
      }
    },
    "FeePolicy": {
      "description": "Defines the ways to calculate the protocol fee.\n",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "surplus": {
              "$ref": "#/$defs/Surplus"
            }
          },
          "required": [
            "surplus"
          ]
        },
        {
          "type": "object",
          "properties": {
            "volume": {
              "$ref": "#/$defs/Volume"
            }
          },
          "required": [
            "volume"
          ]
        },
        {
          "type": "object",
          "properties": {
            "priceImprovement": {
              "$ref": "#/$defs/PriceImprovement"
            }
          },
          "required": [
            "priceImprovement"
          ]
        }
      ]
    },
    "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": "#/$defs/Quote"
            }
          ]
        }
      },
      "required": [
        "factor",
        "maxVolumeFactor",
        "quote"
      ]
    },
    "Quote": {
      "description": "A calculated order quote used in solver auctions.\n",
      "type": "object",
      "properties": {
        "sellAmount": {
          "description": "The amount of the sell token.",
          "allOf": [
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        },
        "buyAmount": {
          "description": "The amount of the buy token.",
          "allOf": [
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        },
        "fee": {
          "description": "The amount that needs to be paid, denominated in the sell token.",
          "allOf": [
            {
              "$ref": "#/$defs/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"
      ]
    },
    "TokenAmount": {
      "description": "Amount of a token. `uint256` encoded in decimal.",
      "type": "string"
    },
    "TransactionHash": {
      "description": "32 byte digest encoded as a hex with `0x` prefix.",
      "type": "string"
    },
    "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"
    },
    "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"
      ]
    }
  }
}