App Data

Overview

App Data is a flexible metadata system enabling developers to attach additional information to CoW Protocol orders. It supports developer attribution, analytics tracking, custom hooks, and more.

What is App Data?

App Data is a 32-byte hash (bytes32) stored in every order that points to a JSON document containing metadata. The document can include slippage tolerance, order classification, UTM tracking, partner fees, CoW Hooks, and custom application data.

const order = {
  appData: '0x8e4f5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e',
}

App Data Structure

interface AppDataDoc {
  version: string
  appCode: string
  environment?: string
  metadata: {
    quote?: {
      slippageBips: number
    }
    orderClass?: {
      orderClass: 'market' | 'limit' | 'liquidity' | 'twap'
    }
    utm?: {
      utmSource?: string
      utmMedium?: string
      utmCampaign?: string
      utmContent?: string
      utmTerm?: string
    }
    hooks?: {
      pre?: CoWHook[]
      post?: CoWHook[]
    }
    partnerFee?: {
      bps: number
      recipient: string
    }
  }
}

Creating App Data

Basic Usage

import { buildAppData } from '@cowprotocol/cow-sdk'

const appDataInfo = await buildAppData({
  appCode: 'MyTradingApp',
  slippageBps: 50,
  orderClass: 'market',
})

// Returns:
// {
//   doc: { /* full app data document */ },
//   fullAppData: '{ ... }',
//   appDataKeccak256: '0x...'
// }

Using in Orders

const { appDataKeccak256 } = await buildAppData({
  appCode: 'MyApp',
  slippageBps: 50,
  orderClass: 'market',
})

const order = {
  sellToken: '0x...',
  buyToken: '0x...',
  appData: appDataKeccak256,
}

Default UTM Parameters

The SDK automatically includes UTM parameters:

const defaultUtm = {
  utmCampaign: 'developer-cohort',
  utmContent: '',
  utmMedium: 'cow-sdk@X.Y.Z',
  utmSource: 'cowmunity',
  utmTerm: 'js',
}

Overriding UTM Parameters

const appDataInfo = await buildAppData(
  {
    appCode: 'MyApp',
    slippageBps: 50,
    orderClass: 'market',
  },
  {
    metadata: {
      utm: {
        utmSource: 'my-platform',
        utmMedium: 'web-app',
        utmCampaign: 'launch-week',
      },
    },
  }
)

Custom UTM parameters completely replace the defaults when provided.

Partner Fees

const appDataInfo = await buildAppData({
  appCode: 'MyApp',
  slippageBps: 50,
  orderClass: 'market',
  partnerFee: {
    bps: 25,
    recipient: '0x1234...',
  },
})

Partner fees are deducted from order surplus and don’t affect minimum user output.

CoW Hooks

CoW Hooks execute custom contract calls before and/or after order execution, enabling token approvals, reward claiming, staking, and arbitrary DeFi operations.

Hook Structure

interface CoWHook {
  target: string
  callData: string
  gasLimit: string
}

Pre-Hooks Example

import { encodeFunctionData } from 'viem'

const approveCallData = encodeFunctionData({
  abi: ERC20_ABI,
  functionName: 'approve',
  args: [SPENDER_ADDRESS, MAX_UINT256],
})

const appDataInfo = await buildAppData(
  {
    appCode: 'MyApp',
    slippageBps: 50,
    orderClass: 'market',
  },
  {
    metadata: {
      hooks: {
        pre: [
          {
            target: TOKEN_ADDRESS,
            callData: approveCallData,
            gasLimit: '50000',
          },
        ],
      },
    },
  }
)

Post-Hooks Example

const stakeCallData = encodeFunctionData({
  abi: STAKING_ABI,
  functionName: 'stake',
  args: [AMOUNT],
})

const appDataInfo = await buildAppData(
  {
    appCode: 'MyApp',
    slippageBps: 50,
    orderClass: 'market',
  },
  {
    metadata: {
      hooks: {
        post: [
          {
            target: STAKING_CONTRACT,
            callData: stakeCallData,
            gasLimit: '100000',
          },
        ],
      },
    },
  }
)

Hook Limitations:

Hooks execute in the same transaction as the order
Failed hooks cause the entire transaction to revert
Set appropriate gas limits to avoid out-of-gas errors
Only use trusted contracts as hook targets

Advanced Usage

Merging App Data

import { mergeAppDataDoc } from '@cowprotocol/cow-sdk'

const existingDoc = await buildAppData({
  appCode: 'MyApp',
  slippageBps: 50,
  orderClass: 'market',
})

const mergedAppData = await mergeAppDataDoc(
  existingDoc.doc,
  {
    metadata: {
      referrer: {
        address: '0x...',
      },
    },
  }
)

Custom Metadata Fields

const appDataInfo = await buildAppData(
  {
    appCode: 'MyApp',
    slippageBps: 50,
    orderClass: 'market',
  },
  {
    environment: 'production',
    metadata: {
      signer: '0x...',
      referrer: {
        address: '0x...',
      },
    },
  }
)

IPFS Integration

const { fullAppData, appDataKeccak256 } = await buildAppData({
  appCode: 'MyApp',
  slippageBps: 50,
  orderClass: 'market',
})

import { keccak256, toUtf8Bytes } from 'ethers'
const computedHash = keccak256(toUtf8Bytes(fullAppData))
// computedHash === appDataKeccak256

The CoW Protocol API automatically uploads app data to IPFS when you submit orders.

Retrieving App Data

import { MetadataApi } from '@cowprotocol/sdk-app-data'
import { getGlobalAdapter } from '@cowprotocol/cow-sdk'

const metadataApi = new MetadataApi(getGlobalAdapter())

const appDataDoc = await metadataApi.fetchDocFromAppData(
  '0x8e4f5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e5e'
)

console.log(appDataDoc.metadata.quote?.slippageBips)

Common Patterns

Market Order:

const appData = await buildAppData({
  appCode: 'MyTradingApp',
  slippageBps: 50,
  orderClass: 'market',
})

Limit Order:

const appData = await buildAppData({
  appCode: 'MyTradingApp',
  slippageBps: 0,
  orderClass: 'limit',
})

With Partner Fee:

const appData = await buildAppData({
  appCode: 'MyTradingApp',
  slippageBps: 50,
  orderClass: 'market',
  partnerFee: {
    bps: 10,
    recipient: '0x...',
  },
})

With Custom UTM:

const appData = await buildAppData(
  {
    appCode: 'MyApp',
    slippageBps: 50,
    orderClass: 'market',
  },
  {
    metadata: {
      utm: {
        utmSource: 'twitter',
        utmMedium: 'social',
        utmCampaign: 'launch',
      },
    },
  }
)

Best Practices

Use Descriptive App Codes: Choose clear, unique identifiers for analytics
Set Appropriate Slippage: Market orders 0.5-1%, limit orders 0%, volatile tokens higher
Test Hooks Thoroughly: Always test on testnets before production
Cache App Data Hashes: Reuse identical metadata hashes to reduce IPFS uploads

Troubleshooting

App data hash mismatch: Ensure the exact fullAppData JSON string with deterministic formatting is used. The SDK handles this automatically. Hook execution failed: Verify target contract address, callData encoding matches function signature, gasLimit is sufficient, and test hook separately. Custom UTM not appearing: When providing metadata.utm, it replaces all defaults. Set all desired UTM fields explicitly.

Next Steps

Order Types - Learn about different order types
Trading SDK - Start building with the SDK
Hooks Guide - Advanced hooks implementation

Getting Started

Concepts

Guides

Advanced

Examples

API Reference

Migration

App Data

App Data

Overview

What is App Data?

App Data Structure

Creating App Data

Basic Usage

Using in Orders

Default UTM Parameters

Overriding UTM Parameters

Partner Fees

CoW Hooks

Hook Structure

Pre-Hooks Example

Post-Hooks Example

Advanced Usage

Merging App Data

Custom Metadata Fields

IPFS Integration

Retrieving App Data

Common Patterns

Best Practices

Troubleshooting

Next Steps

​App Data

​Overview

​What is App Data?

​App Data Structure

​Creating App Data

​Basic Usage

​Using in Orders

​Default UTM Parameters

​Overriding UTM Parameters

​Partner Fees

​CoW Hooks

​Hook Structure

​Pre-Hooks Example

​Post-Hooks Example

​Advanced Usage

​Merging App Data

​Custom Metadata Fields

​IPFS Integration

​Retrieving App Data

​Common Patterns

​Best Practices

​Troubleshooting

​Next Steps

App Data

Overview

What is App Data?

App Data Structure

Creating App Data

Basic Usage

Using in Orders

Default UTM Parameters

Overriding UTM Parameters

Partner Fees

CoW Hooks

Hook Structure

Pre-Hooks Example

Post-Hooks Example

Advanced Usage

Merging App Data

Custom Metadata Fields

IPFS Integration

Retrieving App Data

Common Patterns

Best Practices

Troubleshooting

Next Steps