DOCUMENTATIONDeveloper
Developer
Documentation
Everything you need to integrate ERC-8021, x402, and ERC-8004 into your application. From quick start guides to advanced implementations.
Quick Start
1. INSTALL
Install the ERC-8021 SDK via npm:
npm install @erc8021/sdk
2. INITIALIZE
Initialize the client in your app:
import { ERC8021 } from '@erc8021/sdk';
const client = new ERC8021({
chainId: 1,
code: 'myapp'
});
3. ATTRIBUTE
Add attribution to transactions:
const tx = await client
.appendAttribution(
txData,
['myapp', 'partner']
);
🎉 That's it!
Your transactions now include ERC-8021 attribution. Revenue sharing and analytics will work automatically.
Integration Guides
React / Next.js Integration
Step 1: Create Attribution Hook
// hooks/useAttribution.ts
import { useCallback } from 'react';
import { ERC8021 } from '@erc8021/sdk';
export const useAttribution = (appCode: string) => {
const client = new ERC8021({ chainId: 1, code: appCode });
const addAttribution = useCallback(async (txData: string, partners?: string[]) => {
const codes = partners ? [appCode, ...partners] : [appCode];
return await client.appendAttribution(txData, codes);
}, [appCode]);
return { addAttribution };
};
Step 2: Use in Components
// components/SendTransaction.tsx
import { useAttribution } from '@/hooks/useAttribution';
export const SendTransaction = () => {
const { addAttribution } = useAttribution('myapp');
const handleSend = async () => {
const txData = '0x...'; // Your transaction data
const attributedTx = await addAttribution(txData, ['partner1']);
// Send attributed transaction
await wallet.sendTransaction(attributedTx);
};
return <button onClick={handleSend}>Send with Attribution</button>;
};
Wagmi Integration
import { useSendTransaction } from 'wagmi';
import { ERC8021 } from '@erc8021/sdk';
const client = new ERC8021({ chainId: 1, code: 'myapp' });
export const MyComponent = () => {
const { sendTransaction } = useSendTransaction();
const sendWithAttribution = async () => {
const txData = '0x...';
const attributed = await client.appendAttribution(txData, ['myapp']);
sendTransaction({
to: '0x...',
data: attributed,
});
};
return <button onClick={sendWithAttribution}>Send</button>;
};
Smart Contract Integration
For protocols that want to read attribution data on-chain:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "@erc8021/contracts/AttributionReader.sol";
contract MyProtocol {
AttributionReader public reader;
constructor(address _reader) {
reader = AttributionReader(_reader);
}
function processWithAttribution() external {
// Read attribution from calldata
(string[] memory codes, bool valid) = reader.parseAttribution(msg.data);
if (valid && codes.length > 0) {
// Distribute rewards to attributed entities
for (uint i = 0; i < codes.length; i++) {
address payoutAddr = reader.getPayoutAddress(codes[i]);
// Send rewards...
}
}
}
}
x402 Protocol Integration
Client-Side (User)
Open a payment channel and sign micropayments:
import { X402Client } from '@erc8021/x402';
const client = new X402Client({
provider: window.ethereum,
channelContract: '0x...'
});
// Open channel with 1 ETH deposit
await client.openChannel('0x1 ETH');
// Sign micropayment (0.0001 ETH)
const signature = await client.signPayment({
amount: '0.0001 ETH',
nonce: 1,
recipient: providerAddress
});
// Send to provider
await fetch('/api/content', {
headers: {
'X-Payment-Signature': signature
}
});
Server-Side (Provider)
Verify signatures and deliver content:
import { X402Server } from '@erc8021/x402';
const server = new X402Server({
channelContract: '0x...',
privateKey: process.env.PRIVATE_KEY
});
app.get('/api/content', async (req, res) => {
const signature = req.headers['x-payment-signature'];
// Verify payment signature
const valid = await server.verifyPayment(signature);
if (!valid) {
return res.status(402).json({
error: 'Payment Required',
amount: '0.0001 ETH',
recipient: server.address
});
}
// Deliver content
res.json({ content: '...' });
});
Best Practices
DO
- ✅ Use meaningful, readable codes (e.g., "myapp", not "0x123")
- ✅ Register your code in the canonical registry
- ✅ Include partner codes for revenue sharing
- ✅ Test attribution parsing before production
- ✅ Monitor attribution analytics regularly
- ✅ Keep SDK updated to latest version
DON'T
- ❌ Use special characters in codes
- ❌ Exceed recommended suffix length (256 bytes)
- ❌ Modify attribution data after signing
- ❌ Hardcode attribution in smart contracts
- ❌ Ignore schema validation errors
- ❌ Use unregistered codes in production
API Reference
ERC8021.appendAttribution()
METHODAppends ERC-8021 attribution suffix to transaction data.
Parameters:
- •
txData: string- Original transaction calldata - •
codes: string[]- Array of attribution codes - •
schemaId?: number- Schema ID (default: 0)
Returns:
- •
Promise<string>- Transaction data with attribution suffix
X402Client.signPayment()
METHODCreates a cryptographic signature for a micropayment.
Parameters:
- •
amount: string- Payment amount in ETH - •
nonce: number- Incrementing nonce - •
recipient: string- Provider address
Returns:
- •
Promise<string>- Compact signature
Need Help?
Join our developer community for support, examples, and discussions.