> ## Documentation Index > Fetch the complete documentation index at: https://docs.cow.bleu.builders/llms.txt > Use this file to discover all available pages before exploring further. # Debug an order's lifecycle. > Returns a comprehensive debug report for the given order, including order details, lifecycle events, auction participation, proposed solutions, executions, trades, and settlement attempts. ## OpenAPI ````yaml cow-protocol/reference/apis/openapi/orderbook.yml get /api/v1/debug/order/{uid} 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: Lens (Prod) url: https://api.cow.fi/lens - description: Lens (Staging) url: https://barn.api.cow.fi/lens - description: Linea (Prod) url: https://api.cow.fi/linea - description: Linea (Staging) url: https://barn.api.cow.fi/linea - description: BNB (Prod) url: https://api.cow.fi/bnb - description: BNB (Staging) url: https://barn.api.cow.fi/bnb - description: Plasma (Prod) url: https://api.cow.fi/plasma - description: Plasma (Staging) url: https://barn.api.cow.fi/plasma - description: Ink (Prod) url: https://api.cow.fi/ink - description: Ink (Staging) url: https://barn.api.cow.fi/ink - 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 security: [] paths: /api/v1/debug/order/{uid}: get: summary: Debug an order's lifecycle. description: > Returns a comprehensive debug report for the given order, including order details, lifecycle events, auction participation, proposed solutions, executions, trades, and settlement attempts. operationId: debugOrder parameters: - in: path name: uid schema: $ref: '#/components/schemas/UID' required: true responses: '200': description: Debug report returned. content: application/json: schema: $ref: '#/components/schemas/DebugOrderResponse' '400': description: Invalid order UID (malformed hex or wrong length). '404': description: Order not found. '500': description: Internal error. components: schemas: UID: description: |- Unique identifier for the order: 56 bytes encoded as hex with `0x` prefix. Bytes 0..32 are the order digest, bytes 30..52 the owner address and bytes 52..56 the expiry (`validTo`) as a `uint32` unix epoch timestamp. type: string example: >- 0xff2e2e54d178997f173266817c1e9ed6fee1a1aae4b43971c53b543cffcc2969845c6f5599fbb25dbdd1b9b013daf85c03f3c63763e4bc4a DebugOrderResponse: type: object required: - orderUid - order - events - auctions - trades properties: orderUid: description: The UID of the order being debugged. allOf: - $ref: '#/components/schemas/UID' order: $ref: '#/components/schemas/Order' events: type: array items: $ref: '#/components/schemas/DebugEvent' auctions: description: > Auctions this order participated in, sorted by ID. Each auction groups all related data: native prices, proposed solutions, executions, settlement attempts, and fee policies. type: array items: $ref: '#/components/schemas/DebugAuction' trades: type: array items: $ref: '#/components/schemas/DebugTrade' Order: description: > An order as returned by the API. Combines the order creation data, order metadata, and any associated interactions. allOf: - $ref: '#/components/schemas/OrderCreation' - $ref: '#/components/schemas/OrderMetaData' - type: object properties: interactions: description: > Optional pre and post interactions associated with the order. Pre-interactions are executed before the order's trade, and post-interactions are executed after. type: object properties: pre: description: > Interactions to be executed before the order's trade. These can be used for setup operations like token approvals. type: array items: $ref: '#/components/schemas/InteractionData' post: description: > Interactions to be executed after the order's trade. These can be used for cleanup or follow-up operations. type: array items: $ref: '#/components/schemas/InteractionData' DebugEvent: type: object required: - label - timestamp properties: label: type: string description: Event type (e.g. created, ready, filtered, traded). timestamp: type: string format: date-time reason: type: string nullable: true description: > Why the order was filtered or marked invalid. Only present for "filtered" and "invalid" events. DebugAuction: type: object required: - id - block - deadline - nativePrices - proposedSolutions - executions - settlementAttempts - feePolicies properties: id: type: integer description: Auction ID. block: type: integer description: Block number of the auction. deadline: type: integer description: Deadline block for the auction. nativePrices: type: object additionalProperties: type: string description: > Native prices for the order's sell and buy tokens in this auction. Keys are hex-encoded token addresses, values are decimal price strings. proposedSolutions: type: array items: $ref: '#/components/schemas/DebugProposedSolution' executions: type: array items: $ref: '#/components/schemas/DebugExecution' settlementAttempts: type: array items: $ref: '#/components/schemas/DebugSettlementAttempt' feePolicies: type: array items: $ref: '#/components/schemas/DebugFeePolicy' DebugTrade: type: object required: - blockNumber - logIndex - buyAmount - sellAmount - sellAmountBeforeFees properties: blockNumber: type: integer logIndex: type: integer buyAmount: $ref: '#/components/schemas/TokenAmount' sellAmount: $ref: '#/components/schemas/TokenAmount' sellAmountBeforeFees: $ref: '#/components/schemas/TokenAmount' txHash: $ref: '#/components/schemas/TransactionHash' auctionId: type: integer 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. 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. type: integer nullable: true appData: description: > This field comes in two forms for backward compatibility. The hash form will eventually stop being accepted. anyOf: - title: Full App Data allOf: - $ref: '#/components/schemas/AppData' description: >- **Short**: If 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`. **Long**: A string encoding a JSON object like `"{"hello":"world"}"`. This 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. The 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`. The intended use of the other keys of the object is follow the standardized format defined [here](https://github.com/cowprotocol/app-data). Example: ```json { "version": "0.7.0", "appCode": "YOUR_APP_CODE", "metadata": {} } ``` The 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. allOf: - $ref: '#/components/schemas/AppDataHash' nullable: true fullBalanceCheck: description: > If set to true, full sell amount will be checked during allowance and balance checking. This will ensure the account has correct allowance and available balance for the order to be created. type: boolean default: false 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. 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: description: > The class of the order (market, limit, or liquidity). Determines how fees are handled. allOf: - $ref: '#/components/schemas/OrderClass' owner: description: > The address that signed the order and owns it. For regular orders, this is the trader. For EIP 1271 orders, it's the respective contract (see `onchainUser` for the actual trader). allOf: - $ref: '#/components/schemas/Address' uid: description: > Unique identifier of the order. Computed as the EIP-712 hash of the order data combined with the owner address and valid_to timestamp. allOf: - $ref: '#/components/schemas/UID' availableBalance: description: > Unused field that is currently always set to `null` and will be removed in the future. 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. 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. allOf: - $ref: '#/components/schemas/BigUint' executedBuyAmount: description: > The total amount of `buyToken` that has been executed for this order. 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. 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 orders but are not placed with the intent of actively getting traded. Instead they facilitate the trade of normal orders by allowing them to be matched against liquidity orders which uses less gas and can have better prices than external liquidity. As such liquidity orders will only be used in order to improve settlement of normal orders. They should not be expected to be traded otherwise and should not expect to get surplus. type: boolean ethflowData: description: > Additional data specific to ethflow orders. Only present for orders placed through the EthFlow contract, which allows trading native ETH directly without wrapping to WETH first. allOf: - $ref: '#/components/schemas/EthflowData' onchainUser: description: > This represents the actual trader of an on-chain order. ### ethflow orders In this case, the `owner` would be the `EthFlow` contract and *not* the actual trader. 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. 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. 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. type: string nullable: true settlementContract: description: > The address of the CoW Protocol settlement contract that this order is valid for. Orders are only valid on the settlement contract they were signed for. allOf: - $ref: '#/components/schemas/Address' quote: description: > If the order was created with a quote, this field contains the original quote data for reference. Includes gas estimation and pricing information captured at the time of quoting, which can be used to analyze order execution and calculate fees. allOf: - $ref: '#/components/schemas/StoredOrderQuote' nullable: true required: - creationDate - class - owner - uid - executedSellAmount - executedSellAmountBeforeFees - executedBuyAmount - executedFeeAmount - invalidated - status - settlementContract InteractionData: description: > Represents a smart contract interaction that can be executed as part of an order's pre or post hooks. type: object properties: target: description: The address of the contract to call. allOf: - $ref: '#/components/schemas/Address' value: description: > The amount of native token (ETH, xDAI, etc.) in Wei to send with the interaction call. allOf: - $ref: '#/components/schemas/TokenAmount' callData: description: > The calldata to be sent to the target contract. Encoded as a hex string with `0x` prefix. allOf: - $ref: '#/components/schemas/CallData' required: - target - value - callData DebugProposedSolution: type: object required: - solutionUid - ranking - solver - isWinner - filteredOut - score - executedSell - executedBuy properties: solutionUid: type: integer ranking: type: integer solver: $ref: '#/components/schemas/Address' isWinner: type: boolean filteredOut: type: boolean score: type: string description: Decimal-encoded score. executedSell: $ref: '#/components/schemas/TokenAmount' executedBuy: $ref: '#/components/schemas/TokenAmount' DebugExecution: type: object required: - executedFee - executedFeeToken - blockNumber - protocolFees properties: executedFee: $ref: '#/components/schemas/TokenAmount' executedFeeToken: $ref: '#/components/schemas/Address' blockNumber: type: integer protocolFees: type: array items: $ref: '#/components/schemas/DebugProtocolFee' DebugSettlementAttempt: type: object required: - solver - solutionUid - startTimestamp - startBlock - deadlineBlock properties: solver: $ref: '#/components/schemas/Address' solutionUid: type: integer startTimestamp: type: string format: date-time endTimestamp: type: string format: date-time startBlock: type: integer endBlock: type: integer deadlineBlock: type: integer outcome: type: string description: Settlement outcome (e.g. "success", "revert"). DebugFeePolicy: type: object description: Fee policy applied to this order in this auction. required: - kind properties: kind: type: string enum: - surplus - volume - priceImprovement surplusFactor: type: number surplusMaxVolumeFactor: type: number volumeFactor: type: number priceImprovementFactor: type: number priceImprovementMaxVolumeFactor: type: number TokenAmount: description: Amount of a token. `uint256` encoded in decimal. type: string example: '1234567890' 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' OrderKind: description: Is this order a buy or sell? type: string enum: - buy - sell 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 SigningScheme: description: How was the order signed? type: string enum: - eip712 - ethsign - presign - eip1271 Signature: description: A signature. oneOf: - title: ECDSA Signature allOf: - $ref: '#/components/schemas/EcdsaSignature' - title: Pre-Signature allOf: - $ref: '#/components/schemas/PreSignature' AppData: description: | The string encoding of a JSON object representing some `appData`. The format of the JSON expected in the `appData` field is defined [here](https://github.com/cowprotocol/app-data). type: string example: '{"version":"0.9.0","metadata":{}}' AppDataHash: description: > 32 bytes encoded as hex with `0x` prefix. It's expected to be the hash of the stringified JSON object representing the `appData`. type: string example: '0x0000000000000000000000000000000000000000000000000000000000000000' OrderClass: description: Order class. type: string enum: - market - limit - liquidity BigUint: description: A big unsigned integer encoded in decimal. type: string example: '1234567890' OrderStatus: description: The current order status. type: string enum: - presignaturePending - open - fulfilled - cancelled - expired EthflowData: description: Provides the additional data for ethflow orders. type: object properties: refundTxHash: description: | Specifies in which transaction the order was refunded. If this field is null the order was not yet refunded. allOf: - $ref: '#/components/schemas/TransactionHash' nullable: true userValidTo: description: | Describes the `validTo` of an order ethflow order. **NOTE**: For ethflow orders, the `validTo` encoded in the smart contract is `type(uint256).max`. type: integer required: - refundTxHash - userValidTo 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. 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. type: string enum: - QuoteNotFound - ValidToTooFarInFuture - PreValidationError required: - sender StoredOrderQuote: description: > Quote data stored with an order. This represents the original quote used to create the order, containing gas estimation and pricing information captured at the time of quoting. Note: This is different from `OrderQuoteResponse` which is returned by the `POST /api/v1/quote` endpoint and contains order parameters to sign. type: object properties: gasAmount: description: | The estimated gas units required to execute the quoted trade. Measured in gas units (not Wei). Used together with `gasPrice` and `sellTokenPrice` to calculate the network fee in sell token atoms. type: string example: '150000' gasPrice: description: > The estimated gas price at the time of quoting, measured in Wei per gas unit. The network fee in Wei can be calculated as: `feeInWei = gasAmount * gasPrice`. type: string example: '15000000000' sellTokenPrice: description: > The price of the sell token expressed in native token atoms per sell token atom. Units: `native token atoms / sell token atoms` **Example calculation (Mainnet, selling USDC):** - Sell token: USDC (6 decimals) - Native token: ETH (18 decimals) - Market price: 1 ETH = 1000 USDC `sellTokenPrice = 1 × 10^18 wei / (1000 × 10^6 USDC atoms) = 10^9` This value is used to convert network fees (in native token) to sell token amounts. type: string example: '1000000000' sellAmount: description: The quoted sell amount in atoms of the sell token. allOf: - $ref: '#/components/schemas/TokenAmount' buyAmount: description: The quoted buy amount in atoms of the buy token. allOf: - $ref: '#/components/schemas/TokenAmount' feeAmount: description: > The fee amount in atoms of the sell token, calculated from the gas parameters at the time of quoting. Computed as: `ceil((gasAmount * gasPrice) / sellTokenPrice)`. This represents the network fee that was estimated when the quote was created. allOf: - $ref: '#/components/schemas/TokenAmount' solver: description: The address of the solver that provided this quote. allOf: - $ref: '#/components/schemas/Address' verified: description: | Whether the quote was verified through simulation. A verified quote provides higher confidence that the trade will execute successfully. type: boolean metadata: description: > Additional metadata about the quote execution plan (e.g., the route taken). This field is only populated for orders that are no longer fillable (filled, cancelled, or expired) to prevent solvers from copying execution strategies for active orders. type: object required: - gasAmount - gasPrice - sellTokenPrice - sellAmount - buyAmount - feeAmount - solver - verified CallData: description: >- Some `calldata` sent to a contract in a transaction encoded as a hex with `0x` prefix. type: string example: '0xca11da7a' DebugProtocolFee: type: object required: - token - amount properties: token: $ref: '#/components/schemas/Address' amount: $ref: '#/components/schemas/TokenAmount' 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 ````