Skip to main content

Application specific data

There are times when attaching additional information to an order is useful. For example:

  • An integration partner might want to track the volume they bring to the protocol
  • A user might want to include a referral address in their order
  • A user might want to specify additional order options, such as CoW Hooks

CoW Protocol facilitates the inclusion of this additional information to any order through a special data field known as appData. This field is a bytes32 that points to an IPFS document that is a JSON file containing this information. Utilizing only on-chain data and IPFS, the content of this document can be retrieved and parsed.

AppData Document​

The AppData document is a JSON file that follows a specific JSON schema. It is versioned and the version is specified in the document itself. Versioning follows Semantic Versioning.

An example of an AppData document is:

{
  "version": "1.3.0",
  "appCode": "MyAwesomeUi",
  "metadata": {
    "referral": "0x1234567890123456789012345678901234567890"
  }
}
tip

Avoid all the pain of creating and parsing appData by using either the:

caution

If not using the CoW Explorer appData utility or the app-data SDK, make sure to follow the appData schema and upload your file to IPFS before placing orders using the resulting digest.

Schema​

The schema for the AppData document is defined in JSON schema. The schema is available in the app-data SDK. The schema is shown below:

AppData Root Schema
type : object
  • version Version required readOnly
    type : string
    🚨 read only
    Default value : 1.3.0
    Semantic versioning of document.
  • appCode App Code
    type : string
    The code identifying the CLI, UI, service generating the order.
  • environment Environment
    type : string
    Environment from which the order came from.
  • metadata Metadata required
    type : object
    • signer Signer
      type : string
      Pattern : ^0x[a-fA-F0-9]{40}$
      The address of the trader who signs the CoW Swap order. This field should normally be omitted; it is recommended to use it if the signer is a smart-contract wallet using EIP-1271 signatures.
    • referrer Referrer
      type : object
      • address Referrer address required
        type : string
        Pattern : ^0x[a-fA-F0-9]{40}$
      🚨 No extra propertie(s) are authorized in this object
    • utm UTM Codes
      type : object
      • utmSource UTM Source
        type : string
        Tracks in which medium the traffic originated from (twitter, facebook, etc.)
      • utmMedium UTM Medium
        type : string
        Tracks in which medium the traffic originated from (mail, CPC, social, etc.)
      • utmCampaign UTM Campaign
        type : string
        Track the performance of a specific campaign
      • utmContent UTM Content
        type : string
        Track which link was clicked
      • utmTerm UTM Keyword Term
        type : string
        Track which keyword term a website visitor came from
      🚨 No extra propertie(s) are authorized in this object
    • quote Quote
      type : object
      • slippageBips Basis Point (BPS) required
        type : integer
        Possible values : >= 0 AND <= 10000
        The fee in basis points (BPS) to be paid to the partner. One basis point is equivalent to 0.01% (1/100th of a percent)
      • smartSlippage Smart Slippage
        type : boolean
        Default value : false
        Whether the given slippageBips used is originated from a Smart slippage suggestion
      🚨 No extra propertie(s) are authorized in this object
    • orderClass Order class
      type : object
      • orderClass Order class required
        type : string
        Possible values : 
        ["market","limit","liquidity","twap"]
        Indicator of the order class.
      🚨 No extra propertie(s) are authorized in this object
    • hooks Order interaction hooks
      type : object
      • version Version readOnly
        type : string
        🚨 read only
        Default value : 1.3.0
        Semantic versioning of document.
      • pre Pre-Hooks
        type : array
        • items[x] CoW Hook
          type : object
          • target Referrer address required
            type : string
            Pattern : ^0x[a-fA-F0-9]{40}$
          • callData Hook CallData required
            type : string
            Pattern : ^0x[a-fA-F0-9]*$
            The calldata to use when calling the hook
          • gasLimit Hook Gas Limit required
            type : string
            Pattern : ^\d+$
            The gas limit (in gas units) for the hook
          • dappId Id of the dApp which has built the hook
            type : string
            Pattern : ^[a-fA-F0-9]{64}$
            CoW Swap has an interface that allows dApps to build hooks for orders. This field is used to identify the dApp that has built the hook.
          🚨 No extra propertie(s) are authorized in this object
        CoW Hooks to call before an order executes
      • post Post-Hooks
        type : array
        • items[x] CoW Hook
          type : object
          • target Referrer address required
            type : string
            Pattern : ^0x[a-fA-F0-9]{40}$
          • callData Hook CallData required
            type : string
            Pattern : ^0x[a-fA-F0-9]*$
            The calldata to use when calling the hook
          • gasLimit Hook Gas Limit required
            type : string
            Pattern : ^\d+$
            The gas limit (in gas units) for the hook
          • dappId Id of the dApp which has built the hook
            type : string
            Pattern : ^[a-fA-F0-9]{64}$
            CoW Swap has an interface that allows dApps to build hooks for orders. This field is used to identify the dApp that has built the hook.
          🚨 No extra propertie(s) are authorized in this object
        CoW Hooks to call after an order executes
      🚨 No extra propertie(s) are authorized in this object
      Default value : 
      {}
      Optional Pre and Post order interaction hooks attached to a single order
    • widget Widget
      type : object
      • appCode App Code required
        type : string
        The code identifying the UI powering the widget
      • environment Environment
        type : string
        Environment from which the order came from.
      🚨 No extra propertie(s) are authorized in this object
    • partnerFee Partner fee
      type : object
      • bps Basis Point (BPS) required
        type : integer
        Possible values : >= 0 AND <= 10000
        The fee in basis points (BPS) to be paid to the partner. One basis point is equivalent to 0.01% (1/100th of a percent)
      • recipient Referrer address required
        type : string
        Pattern : ^0x[a-fA-F0-9]{40}$
      🚨 No extra propertie(s) are authorized in this object
    • replacedOrder Replaced order
      type : object
      • uid Replaced order UID required
        type : string
        Pattern : ^0x[a-fA-F0-9]{112}$
        The replaced order UID.
      🚨 No extra propertie(s) are authorized in this object
    🚨 No extra propertie(s) are authorized in this object
    Default value : 
    {}
    Each metadata will specify one aspect of the order.
🚨 No extra propertie(s) are authorized in this object
Metadata JSON document for adding information to orders.