MetadataApi
Overview
The MetadataApi class is a utility for managing CoW Protocol order metadata (app-data). It handles schema validation, document generation, IPFS hashing, and format conversions.
Installation
npm install @cowprotocol/sdk-app-data
Key Methods
generateAppDataDoc
Creates an app-data document using the current schema version, accepting parameters like appCode, environment, and nested metadata properties (referrer, quote, orderClass, hooks, partnerFee).
getAppDataInfo
Processes an app-data document to return three outputs:
appDataHex - the hex representation for use in ordersappDataContent - the original JSON contentcid - the IPFS identifier
validateAppDataDoc
Checks whether a document complies with its corresponding schema, returning a success boolean and any error descriptions.
getAppDataSchema
Retrieves the JSON schema definition for a specified version, useful for custom validation workflows.
Conversion Utilities
appDataHexToCid / cidToAppDataHex - Bidirectional conversion between hex and IPFS identifiersfetchDocFromAppDataHex - Retrieves a stored document from IPFS using its hex representation
Practical Example
To create an order with metadata, generate a document, extract its hex value, and pass it to the trading SDK:
const appDataDoc = await metadataApi.generateAppDataDoc({
appCode: 'My Trading App',
metadata: {
referrer: { address: '0x...' },
quote: { slippageBips: 50 },
},
})
const { appDataHex } = await metadataApi.getAppDataInfo(appDataDoc)
Supported Features
The API supports order hooks (pre/post interactions), partner fee configurations, order classification (market/limit/liquidity), and referrer tracking.
Best Practices
- Always validate documents before use
- Leverage the latest schema automatically
- Cache identical metadata results
- Include referrer information for tracking
- Document any hooks for security purposes
Last modified on March 4, 2026
