Integration Guide
Integrate Bench into your agent in minutes. One API call to certify best-execution.
Quick Start
1. Request a Certified Quote
// POST /v1/certify
const response = await fetch('https://attestor.usebench.xyz/v1/certify', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your-api-key',
},{',
body: JSON.stringify({
inputToken: '0xEeeeeE...', // ETH
outputToken: '0xA0b86...', // USDC
inputAmount: '1000000000000000000', // 1 ETH in wei
chainId: 196,
agentAddress: '0xYourAgent...',
})
});
const response = await fetch('https://attestor.usebench.xyz/v1/certify', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your-api-key',
},{',
body: JSON.stringify({
inputToken: '0xEeeeeE...', // ETH
outputToken: '0xA0b86...', // USDC
inputAmount: '1000000000000000000', // 1 ETH in wei
chainId: 196,
agentAddress: '0xYourAgent...',
})
});
2. Use the Certificate
const cert = await response.json();
// Execute the swap using the best source
console.log(cert.bestSource); // "1inch"
console.log(cert.bestOutputAmount); // "2847320000"
console.log(cert.certificationLevel); // "CERTIFIED"
// Store the certificate for proof
console.log(cert.certHash); // "0xabc..."
console.log(cert.signature); // EIP-712 signature
// Execute the swap using the best source
console.log(cert.bestSource); // "1inch"
console.log(cert.bestOutputAmount); // "2847320000"
console.log(cert.certificationLevel); // "CERTIFIED"
// Store the certificate for proof
console.log(cert.certHash); // "0xabc..."
console.log(cert.signature); // EIP-712 signature
3. Verify (Optional)
import { verify } from '@usebench/verifier';
const isValid = await verify(cert);
console.log(isValid); // true
const isValid = await verify(cert);
console.log(isValid); // true
API Reference
POST
/v1/certifyRequest a certified best-execution quote. Requires API key.
Request Body
| Field | Type | Description |
|---|---|---|
| inputToken | string | Token address or symbol (e.g., "ETH") |
| outputToken | string | Token address or symbol (e.g., "USDC") |
| inputAmount | string | Amount in smallest unit (wei) |
| chainId | number | Target chain (196 for X Layer) |
| agentAddress | string | Your agent's wallet address |
Read Endpoints (Public)
GET
/v1/statsGlobal statistics (total certs, certified rate, avg agreement)
GET
/v1/certsRecent certificates (paginated)
GET
/v1/certs/:hashSingle certificate by hash
GET
/v1/aggregatorsAggregator performance rankings
GET
/v1/agentsAgent leaderboard
GET
/v1/agents/:addrSingle agent profile and history
Error Handling
The API returns standard HTTP status codes. Errors include a JSON body with details:
{
"error": "Insufficient sources responded",
"code": "INSUFFICIENT_SOURCES",
"sourcesResponded": 1,
"minimumRequired": 2
}
"error": "Insufficient sources responded",
"code": "INSUFFICIENT_SOURCES",
"sourcesResponded": 1,
"minimumRequired": 2
}
| Code | Meaning |
|---|---|
| 400 | Invalid request (missing fields, invalid token) |
| 401 | Missing or invalid API key |
| 429 | Rate limit exceeded |
| 503 | Insufficient sources available |