Get Attestations

curl --request GET \
  --url https://api-mainnet.onzks.com/v1/trust/attestations/:identity \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api-mainnet.onzks.com/v1/trust/attestations/:identity"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-mainnet.onzks.com/v1/trust/attestations/:identity', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-mainnet.onzks.com/v1/trust/attestations/:identity",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-mainnet.onzks.com/v1/trust/attestations/:identity"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-mainnet.onzks.com/v1/trust/attestations/:identity")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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>"
}

GET

trust

attestations

:identity

Get Attestations

curl --request GET \
  --url https://api-mainnet.onzks.com/v1/trust/attestations/:identity \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api-mainnet.onzks.com/v1/trust/attestations/:identity"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-mainnet.onzks.com/v1/trust/attestations/:identity', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-mainnet.onzks.com/v1/trust/attestations/:identity",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-mainnet.onzks.com/v1/trust/attestations/:identity"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-mainnet.onzks.com/v1/trust/attestations/:identity")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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

string

required

User identity (ZKS ID or wallet address)

ZKS ID is recommended for better performance and user experience

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

string

Filter by attestation issuer (ZKS ID or wallet address)

string

Filter by attestation status

active - Active attestations (default)
expired - Expired attestations
revoked - Revoked attestations
all - All attestations regardless of status

string

Filter by attestation category

string

Filter by tags (comma-separated)

boolean

Filter by visibility

true - Public attestations only
false - Private attestations only
null - All attestations (default)

number

Number of attestations to return (default: 50, max: 100)

number

Number of attestations to skip for pagination (default: 0)

string

Sort attestations by field

createdAt - By creation date (default)
expiry - By expiry date
trustScore - By trust score
schema - By schema type

string

Sort order

desc - Descending (default)
asc - Ascending

boolean

Include detailed metadata (default: true)

boolean

Include evidence data (default: true)

Response

boolean

Indicates if the request was successful

string

Resolved wallet address

string

ZKS ID if available, null otherwise

array

Array of attestation objects

Show attestation properties

string

Attestation identifier

string

Attested identity

string

Attestation issuer

string

Attestation schema

object

Attestation data

Show data properties

string

Attestation title

string

Attestation description

string

Attestation category

string

Attestation value

object

Additional metadata

array

Supporting evidence

string

Attestation signature

string

ISO 8601 timestamp of creation

string

ISO 8601 timestamp of expiry (if set)

boolean

Whether attestation can be revoked

boolean

Whether attestation is publicly visible

string

Attestation status (active, expired, revoked)

array

Attestation tags

object

Verification details

Show verification properties

boolean

Whether attestation is verified

string

Method used for verification

string

ISO 8601 timestamp of verification

number

Trust score of the attestation

object

Pagination information

Show pagination properties

number

Total number of attestations

number

Number of attestations returned

number

Current offset

boolean

Whether more attestations are available

object

Attestation summary statistics

Show summary properties

number

Total number of attestations

number

Number of active attestations

number

Number of expired attestations

number

Number of revoked attestations

object

Breakdown by schema type

object

Breakdown by category

number

Average trust score across all attestations

number

Number of verified attestations

string

ISO 8601 timestamp of the response

Examples

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

curl "https://api.onzks.com/v1/trust/attestations/alice.zks?schema=skill&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.onzks.com/v1/trust/attestations/alice.zks?public=true&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

async function getAttestations(identity, options = {}) {
  const {
    schema,
    issuer,
    status = 'active',
    category,
    tags,
    public: isPublic,
    limit = 50,
    offset = 0,
    sortBy = 'createdAt',
    sortOrder = 'desc',
    includeMetadata = true,
    includeEvidence = true
  } = options;

  const params = new URLSearchParams({
    status,
    limit: limit.toString(),
    offset: offset.toString(),
    sortBy,
    sortOrder,
    includeMetadata: includeMetadata.toString(),
    includeEvidence: includeEvidence.toString()
  });

  if (schema) params.append('schema', schema);
  if (issuer) params.append('issuer', issuer);
  if (category) params.append('category', category);
  if (tags) params.append('tags', tags);
  if (isPublic !== null) params.append('public', isPublic.toString());

  const response = await fetch(
    `https://api.onzks.com/v1/trust/attestations/${identity}?${params}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  console.log(`Attestations for ${data.zksId || data.address}:`);
  console.log(`Total: ${data.summary.totalAttestations}`);
  console.log(`Active: ${data.summary.activeAttestations}`);
  console.log(`Verified: ${data.summary.verifiedCount}`);
  console.log(`Average Trust Score: ${data.summary.averageTrustScore}`);

  return data;
}

// Usage examples
await getAttestations('alice.zks');
await getAttestations('alice.zks', { schema: 'skill', status: 'active' });
await getAttestations('alice.zks', { public: true, limit: 20 });
await getAttestations('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');

import requests

def get_attestations(identity, schema=None, issuer=None, status='active', category=None,
                    tags=None, public=None, limit=50, offset=0, sort_by='createdAt',
                    sort_order='desc', include_metadata=True, include_evidence=True):
    params = {
        'status': status,
        'limit': limit,
        'offset': offset,
        'sortBy': sort_by,
        'sortOrder': sort_order,
        'includeMetadata': include_metadata,
        'includeEvidence': include_evidence
    }
    
    if schema:
        params['schema'] = schema
    if issuer:
        params['issuer'] = issuer
    if category:
        params['category'] = category
    if tags:
        params['tags'] = tags
    if public is not None:
        params['public'] = public
    
    response = requests.get(
        f'https://api.onzks.com/v1/trust/attestations/{identity}',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        params=params
    )
    
    data = response.json()
    
    print(f"Attestations for {data.get('zksId', data['address'])}:")
    print(f"Total: {data['summary']['totalAttestations']}")
    print(f"Active: {data['summary']['activeAttestations']}")
    print(f"Verified: {data['summary']['verifiedCount']}")
    print(f"Average Trust Score: {data['summary']['averageTrustScore']}")
    
    return data

# Usage examples
get_attestations('alice.zks')
get_attestations('alice.zks', schema='skill', status='active')
get_attestations('alice.zks', public=True, limit=20)
get_attestations('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb')

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
  };
}

Create Attestation - Create new attestations
Revoke Attestation - Revoke attestations
Evaluate Policy - Evaluate trust policies
Get Modules - Get available trust modules

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.

API Documentation

Identity

Scores

Achievements

Trading

Trust Layer

Developer Tools

Get Attestations

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. Reputation Profile

2. Skill Verification

3. Trust Score Calculation

4. Attestation Filtering

5. Attestation Analytics

Best Practices

1. Caching

3. Real-time Updates

4. Verification

Troubleshooting

”No attestations found”

”Invalid schema filter”

”Invalid status filter”

Rate Limits

​Overview

​Parameters

​Response

​Examples

​Response Example

​Use Cases

​1. Reputation Profile

​2. Skill Verification

​3. Trust Score Calculation

​4. Attestation Filtering

​5. Attestation Analytics

​Best Practices

​1. Caching

​2. Pagination

​3. Real-time Updates

​4. Verification

​Related Endpoints

​Troubleshooting

​”No attestations found”

​”Invalid schema filter”

​”Invalid status filter”

​Rate Limits

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. Reputation Profile

2. Skill Verification

3. Trust Score Calculation

4. Attestation Filtering

5. Attestation Analytics

Best Practices

1. Caching

2. Pagination

3. Real-time Updates

4. Verification

Related Endpoints

Troubleshooting

”No attestations found”

”Invalid schema filter”

”Invalid status filter”

Rate Limits