Skip to main content
GET
/
v1
/
trust
/
attestations
/
:identity
Get Attestations
curl --request GET \
  --url https://api-mainnet.onzks.com/v1/trust/attestations/:identity \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "address": "<string>",
  "zksId": "<string>",
  "attestations": [
    {
      "id": "<string>",
      "subject": "<string>",
      "issuer": "<string>",
      "schema": "<string>",
      "data": {
        "title": "<string>",
        "description": "<string>",
        "category": "<string>",
        "value": "<string>",
        "metadata": {},
        "evidence": [
          {}
        ]
      },
      "signature": "<string>",
      "createdAt": "<string>",
      "expiry": "<string>",
      "revocable": true,
      "public": true,
      "status": "<string>",
      "tags": [
        {}
      ],
      "verification": {
        "verified": true,
        "verificationMethod": "<string>",
        "verificationTimestamp": "<string>",
        "trustScore": 123
      }
    }
  ],
  "pagination": {
    "total": 123,
    "limit": 123,
    "offset": 123,
    "hasMore": true
  },
  "summary": {
    "totalAttestations": 123,
    "activeAttestations": 123,
    "expiredAttestations": 123,
    "revokedAttestations": 123,
    "schemaBreakdown": {},
    "categoryBreakdown": {},
    "averageTrustScore": 123,
    "verifiedCount": 123
  },
  "timestamp": "<string>"
}

​
Overview

Retrieve all attestations associated with a specific identity. This endpoint provides comprehensive access to attestations with filtering, sorting, and pagination options, making it perfect for building reputation profiles and trust verification systems.
Use this endpoint to display a user’s attestation collection, verify credentials, and build trust-based applications that rely on verified attributes and relationships.

​
Parameters

​
identity
string
required
User identity (ZKS ID or wallet address)
ZKS ID is recommended for better performance and user experience
​
schema
string
Filter by attestation schema
  • skill - Skill or expertise attestations
  • relationship - Relationship attestations
  • achievement - Achievement attestations
  • reputation - Reputation attestations
  • identity - Identity verification attestations
  • custom - Custom schema attestations
​
issuer
string
Filter by attestation issuer (ZKS ID or wallet address)
​
status
string
Filter by attestation status
  • active - Active attestations (default)
  • expired - Expired attestations
  • revoked - Revoked attestations
  • all - All attestations regardless of status
​
category
string
Filter by attestation category
​
tags
string
Filter by tags (comma-separated)
​
public
boolean
Filter by visibility
  • true - Public attestations only
  • false - Private attestations only
  • null - All attestations (default)
​
limit
number
Number of attestations to return (default: 50, max: 100)
​
offset
number
Number of attestations to skip for pagination (default: 0)
​
sortBy
string
Sort attestations by field
  • createdAt - By creation date (default)
  • expiry - By expiry date
  • trustScore - By trust score
  • schema - By schema type
​
sortOrder
string
Sort order
  • desc - Descending (default)
  • asc - Ascending
​
includeMetadata
boolean
Include detailed metadata (default: true)
​
includeEvidence
boolean
Include evidence data (default: true)

​
Response

​
success
boolean
Indicates if the request was successful
​
address
string
Resolved wallet address
​
zksId
string
ZKS ID if available, null otherwise
​
attestations
array
Array of attestation objects
​
pagination
object
Pagination information
​
summary
object
Attestation summary statistics
​
timestamp
string
ISO 8601 timestamp of the response

​
Examples

curl "https://api.onzks.com/v1/trust/attestations/alice.zks" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response Example

{
  "success": true,
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "zksId": "alice.zks",
  "attestations": [
    {
      "id": "att_1234567890abcdef",
      "subject": "alice.zks",
      "issuer": "0x9876543210fedcba...",
      "schema": "skill",
      "data": {
        "title": "Solidity Developer",
        "description": "Expert in smart contract development",
        "category": "programming",
        "value": "expert",
        "metadata": {
          "yearsExperience": 5,
          "projects": ["DeFi Protocol", "NFT Marketplace"],
          "certifications": ["Certified Solidity Developer"]
        },
        "evidence": [
          {
            "type": "url",
            "value": "https://github.com/alice/solidity-projects",
            "description": "GitHub repository with Solidity projects"
          }
        ]
      },
      "signature": "0xabcdef1234567890...",
      "createdAt": "2024-01-15T10:30:00Z",
      "expiry": "2025-01-15T10:30:00Z",
      "revocable": true,
      "public": true,
      "status": "active",
      "tags": ["solidity", "blockchain", "developer"],
      "verification": {
        "verified": true,
        "verificationMethod": "signature_verification",
        "verificationTimestamp": "2024-01-15T10:30:00Z",
        "trustScore": 85.5
      }
    },
    {
      "id": "att_abcdef1234567890",
      "subject": "alice.zks",
      "issuer": "0x1234567890abcdef...",
      "schema": "relationship",
      "data": {
        "title": "Business Partner",
        "description": "Long-term business partnership",
        "category": "business",
        "value": "trusted",
        "metadata": {
          "relationshipType": "business_partner",
          "duration": "3 years",
          "projects": ["Joint Venture", "Consulting"]
        },
        "evidence": [
          {
            "type": "transaction",
            "value": "0x1234567890abcdef...",
            "description": "Business transaction history"
          }
        ]
      },
      "signature": "0x1234567890abcdef...",
      "createdAt": "2024-01-10T14:20:00Z",
      "expiry": null,
      "revocable": true,
      "public": true,
      "status": "active",
      "tags": ["business", "partnership", "trusted"],
      "verification": {
        "verified": true,
        "verificationMethod": "signature_verification",
        "verificationTimestamp": "2024-01-10T14:20:00Z",
        "trustScore": 92.3
      }
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "summary": {
    "totalAttestations": 15,
    "activeAttestations": 12,
    "expiredAttestations": 2,
    "revokedAttestations": 1,
    "schemaBreakdown": {
      "skill": 8,
      "relationship": 4,
      "achievement": 2,
      "reputation": 1
    },
    "categoryBreakdown": {
      "programming": 5,
      "business": 4,
      "blockchain": 3,
      "leadership": 2,
      "education": 1
    },
    "averageTrustScore": 78.5,
    "verifiedCount": 14
  },
  "timestamp": "2024-01-20T15:45:00Z"
}

​
Use Cases

​
1. Reputation Profile

Create a comprehensive reputation profile: 
function createReputationProfile(attestations) {
  const profile = {
    skills: attestations.filter(a => a.schema === 'skill'),
    relationships: attestations.filter(a => a.schema === 'relationship'),
    achievements: attestations.filter(a => a.schema === 'achievement'),
    reputation: attestations.filter(a => a.schema === 'reputation'),
    identity: attestations.filter(a => a.schema === 'identity')
  };

  return {
    ...profile,
    summary: {
      totalSkills: profile.skills.length,
      totalRelationships: profile.relationships.length,
      totalAchievements: profile.achievements.length,
      averageTrustScore: calculateAverageTrustScore(attestations),
      verifiedCount: attestations.filter(a => a.verification.verified).length
    }
  };
}

​
2. Skill Verification

Verify specific skills: 
function verifySkills(attestations, requiredSkills) {
  const skillAttestations = attestations.filter(a => a.schema === 'skill');
  
  const verifiedSkills = requiredSkills.map(skill => {
    const attestation = skillAttestations.find(a => 
      a.data.title.toLowerCase().includes(skill.toLowerCase()) ||
      a.data.category === skill
    );
    
    return {
      skill,
      verified: !!attestation,
      attestation: attestation || null,
      trustScore: attestation?.verification.trustScore || 0
    };
  });
  
  return verifiedSkills;
}

// Usage
const requiredSkills = ['Solidity', 'React', 'Node.js'];
const skills = verifySkills(attestations, requiredSkills);

​
3. Trust Score Calculation

Calculate overall trust score: 
function calculateTrustScore(attestations) {
  const activeAttestations = attestations.filter(a => a.status === 'active');
  
  if (activeAttestations.length === 0) {
    return 0;
  }
  
  const totalScore = activeAttestations.reduce((sum, attestation) => {
    return sum + attestation.verification.trustScore;
  }, 0);
  
  const averageScore = totalScore / activeAttestations.length;
  
  // Weight by schema type
  const weights = {
    skill: 1.0,
    relationship: 1.2,
    achievement: 1.1,
    reputation: 1.3,
    identity: 1.5
  };
  
  const weightedScore = activeAttestations.reduce((sum, attestation) => {
    const weight = weights[attestation.schema] || 1.0;
    return sum + (attestation.verification.trustScore * weight);
  }, 0);
  
  const totalWeight = activeAttestations.reduce((sum, attestation) => {
    return sum + (weights[attestation.schema] || 1.0);
  }, 0);
  
  return {
    averageScore,
    weightedScore: weightedScore / totalWeight,
    totalAttestations: activeAttestations.length,
    breakdown: groupBySchema(activeAttestations)
  };
}

​
4. Attestation Filtering

Filter attestations by various criteria: 
function filterAttestations(attestations, filters) {
  return attestations.filter(attestation => {
    if (filters.schema && attestation.schema !== filters.schema) return false;
    if (filters.status && attestation.status !== filters.status) return false;
    if (filters.category && attestation.data.category !== filters.category) return false;
    if (filters.public !== null && attestation.public !== filters.public) return false;
    if (filters.verified && !attestation.verification.verified) return false;
    if (filters.minTrustScore && attestation.verification.trustScore < filters.minTrustScore) return false;
    if (filters.tags && !filters.tags.some(tag => attestation.tags.includes(tag))) return false;
    
    return true;
  });
}

// Usage
const filteredAttestations = filterAttestations(attestations, {
  schema: 'skill',
  status: 'active',
  verified: true,
  minTrustScore: 80,
  tags: ['blockchain', 'programming']
});

​
5. Attestation Analytics

Analyze attestation patterns: 
function analyzeAttestations(attestations) {
  const analysis = {
    bySchema: groupBy(attestations, 'schema'),
    byCategory: groupBy(attestations, 'data.category'),
    byStatus: groupBy(attestations, 'status'),
    byIssuer: groupBy(attestations, 'issuer'),
    trustScoreDistribution: calculateTrustScoreDistribution(attestations),
    timeDistribution: calculateTimeDistribution(attestations),
    evidenceTypes: analyzeEvidenceTypes(attestations)
  };
  
  return analysis;
}

function groupBy(array, key) {
  return array.reduce((groups, item) => {
    const value = item[key];
    if (!groups[value]) {
      groups[value] = [];
    }
    groups[value].push(item);
    return groups;
  }, {});
}

​
Best Practices

​
1. Caching

Cache attestation data for performance: 
let attestationCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedAttestations(identity, options = {}) {
  const cacheKey = `${identity}-${JSON.stringify(options)}`;
  const cached = attestationCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await getAttestations(identity, options);
  attestationCache.set(cacheKey, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

​
2. Pagination

Handle large attestation collections: 
async function getAllAttestations(identity, options = {}) {
  const allAttestations = [];
  let offset = 0;
  const limit = 100;
  
  while (true) {
    const data = await getAttestations(identity, {
      ...options,
      limit,
      offset
    });
    
    allAttestations.push(...data.attestations);
    
    if (!data.pagination.hasMore) {
      break;
    }
    
    offset += limit;
  }
  
  return allAttestations;
}

​
3. Real-time Updates

Subscribe to attestation updates: 
function subscribeToAttestationUpdates(identity, callback) {
  const ws = new WebSocket(`wss://api.onzks.com/v1/trust/attestations/${identity}/subscribe`);
  
  ws.onmessage = (event) => {
    const update = JSON.parse(event.data);
    callback(update);
  };
  
  return () => ws.close();
}

​
4. Verification

Verify attestation authenticity: 
async function verifyAttestation(attestation) {
  const message = JSON.stringify({
    subject: attestation.subject,
    schema: attestation.schema,
    data: attestation.data,
    createdAt: attestation.createdAt
  });
  
  const recoveredAddress = await recoverAddress(message, attestation.signature);
  const isValid = recoveredAddress === attestation.issuer;
  
  return {
    valid: isValid,
    issuer: attestation.issuer,
    recoveredAddress,
    message
  };
}

​
Troubleshooting

​
”No attestations found”

Cause: No attestations match the criteria or user has no attestations. Solution:
  • Remove restrictive filters
  • Check if the user has any attestations
  • Verify the identity is correct

​
”Invalid schema filter”

Cause: Unsupported schema value. Solution:
  • Use supported schemas: skill, relationship, achievement, reputation, identity, custom
  • Check for typos

​
”Invalid status filter”

Cause: Unsupported status value. Solution:
  • Use supported statuses: active, expired, revoked, all
  • Check for typos

​
Rate Limits

Attestation requests are subject to rate limits:
  • Free tier: 60 requests per minute
  • Starter tier: 300 requests per minute
  • Professional tier: 1,000 requests per minute
  • Enterprise tier: Custom limits
Implement caching to reduce API calls.