> For the complete documentation index, see [llms.txt](https://docs.dotpassport.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dotpassport.io/examples/basic-usage.md).
# Basic Usage
Get started quickly with these simple examples.
## Quick Start - Widget
The fastest way to display reputation data:
```html
DotPassport Widget
```
***
## Quick Start - API Client
Fetch reputation data programmatically:
```typescript
import { DotPassportClient } from '@dotpassport/sdk';
const client = new DotPassportClient({
apiKey: 'your_api_key'
});
// Get reputation scores
const scores = await client.getScores('5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY');
console.log('Total Score:', scores.totalScore);
console.log('Calculated At:', scores.calculatedAt);
```
***
## Widget Types
### Reputation Widget
Shows overall reputation score with category breakdown:
```typescript
createWidget({
apiKey: 'your_api_key',
address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
type: 'reputation',
showCategories: true,
maxCategories: 6
}).mount('#container');
```
### Badge Widget
Displays earned achievement badges:
```typescript
createWidget({
apiKey: 'your_api_key',
address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
type: 'badge',
maxBadges: 8,
showProgress: true
}).mount('#container');
```
### Profile Widget
Shows user profile with identity information:
```typescript
createWidget({
apiKey: 'your_api_key',
address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
type: 'profile',
showIdentities: true,
showSocials: true,
showBio: true
}).mount('#container');
```
### Category Widget
Displays a specific reputation category:
```typescript
createWidget({
apiKey: 'your_api_key',
address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
type: 'category',
categoryKey: 'governance'
}).mount('#container');
```
***
## API Methods
### Get Scores
```typescript
const scores = await client.getScores(address);
// Response
{
address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
totalScore: 847,
calculatedAt: '2025-01-12T10:30:00Z',
categories: {
longevity: { title: 'Account Longevity', score: 85, reason: 'Account active for 3+ years' },
governance: { title: 'Governance', score: 72, reason: 'Active voter in referenda' },
// ... more categories
},
source: 'api'
}
```
### Get Badges
```typescript
const badges = await client.getBadges(address);
// Response
{
address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
badges: [
{ badgeKey: 'early_adopter', achievedLevel: 2, achievedLevelKey: 'gold', achievedLevelTitle: 'Gold Early Adopter', earnedAt: '2024-06-15T10:00:00Z' },
{ badgeKey: 'voter', achievedLevel: 1, achievedLevelKey: 'bronze', achievedLevelTitle: 'Active Voter', earnedAt: '2024-08-20T14:30:00Z' },
// ... more badges
],
count: 12,
source: 'api'
}
```
### Get Profile
```typescript
const profile = await client.getProfile(address);
// Response
{
address: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
displayName: 'Alice',
avatarUrl: 'https://example.com/avatar.png',
bio: 'Polkadot enthusiast',
socialLinks: { twitter: 'https://twitter.com/alice', github: 'https://github.com/alice' },
polkadotIdentities: [
{ address: '1...', display: 'Alice', twitter: '@alice' }
],
nftCount: 5,
source: 'api'
}
```
***
## React Example
```tsx
import { useEffect, useRef } from 'react';
import { createWidget } from '@dotpassport/sdk';
function ReputationWidget({ address }: { address: string }) {
const containerRef = useRef(null);
useEffect(() => {
if (!containerRef.current) return;
const widget = createWidget({
apiKey: import.meta.env.VITE_DOTPASSPORT_API_KEY,
address,
type: 'reputation'
});
widget.mount(containerRef.current);
return () => widget.destroy();
}, [address]);
return ;
}
// Usage
```
***
## Vue Example
```vue
```
***
## Error Handling
```typescript
import { DotPassportClient, DotPassportError } from '@dotpassport/sdk';
const client = new DotPassportClient({ apiKey: 'your_api_key' });
try {
const scores = await client.getScores(address);
console.log(scores);
} catch (error) {
if (error instanceof DotPassportError) {
switch (error.statusCode) {
case 404:
console.log('Address not found');
break;
case 401:
console.log('Invalid API key');
break;
case 429:
console.log('Rate limited, please wait');
break;
default:
console.log('Error:', error.message);
}
}
}
```
***
## Themes
```typescript
// Light theme (default)
createWidget({
apiKey: 'your_api_key',
address: address,
type: 'reputation',
theme: 'light'
});
// Dark theme
createWidget({
apiKey: 'your_api_key',
address: address,
type: 'reputation',
theme: 'dark'
});
// Auto (follows system preference)
createWidget({
apiKey: 'your_api_key',
address: address,
type: 'reputation',
theme: 'auto'
});
```
***
## Related
* [Custom Themes](/examples/custom-themes.md)
* [Dynamic Updates](/examples/dynamic-updates.md)
* [Multiple Widgets](/examples/multiple-widgets.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.dotpassport.io/examples/basic-usage.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.