PNS API Documentation
Resolve Pentagon Name Service identities in your app, wallet, or service.
Overview
The PNS (Pentagon Name Service) API lets you resolve human-readable names to Pentagon Chain addresses and vice versa. Similar to ENS on Ethereum, PNS names are on-chain NFTs that map @username to wallet addresses.
Base URL: https://id.peg.gg/api/v1
Chain: Pentagon Chain (ID: 3344)
Contract: 0xf97EB9f8293D1FD5587a809Eb74518c300738d07
Authentication & Rate Limits
Public access (no key): 1 request per minute per IP. All endpoints below work without authentication. Suitable for manual lookups, light testing, and low-traffic integrations.
API key access: Unlimited requests. For apps, wallets, exchanges, and services that need production-level throughput.
Try it now: Reverse Lookup on the homepage or call the API directly:
curl https://id.peg.gg/api/v1/reverse/0x1D187Aa2832cC7a3F778B075eEd0268744D3017a
Getting an API Key
API keys are free for legitimate integrations (wallets, exchanges, dApps, analytics). Two ways to request one:
- Email nftprof@pentagon.games
- Join our Discord discord.gg/pentagonchain
Include:
- Your app/project name
- Brief description of your use case
- Expected request volume
Using Your API Key
Include the key as a query parameter or header:
GET /api/v1/resolve/nftprof?key=YOUR_API_KEY
curl -H "X-PNS-Key: YOUR_API_KEY" https://id.peg.gg/api/v1/reverse/0x1234...
Forward Resolve Public
Look up a PNS name to get its owner address, spatial binding, tier, and metadata.
GET /api/v1/resolve/:name
| Parameter | Type | Description |
|---|
name | string | PNS name (e.g. nftprof, @nftprof, or nftprof.peg.gg) |
Example:
curl https://id.peg.gg/api/v1/resolve/nftprof
Response:
{
"ok": true,
"name": "nftprof",
"record": {
"name": "nftprof",
"token_id": 42,
"owner": "0x1234...abcd",
"spatial_binding": "0x5678...efgh",
"tier": "high",
"bound": true,
"forward_url": "https://pentagon.games/acc/nftprof"
}
}
The spatial_binding is the address the name resolves to (set by the owner). If null, the name is minted but not yet bound to an address.
Reverse Resolve Public
Given a wallet address, find the primary PNS name associated with it. Useful for displaying human-readable names in wallets, explorers, and dApps.
GET /api/v1/reverse/:address
| Parameter | Type | Description |
|---|
address | string | Ethereum-format address (0x...) |
Example:
curl https://id.peg.gg/api/v1/reverse/0x5678...efgh
Response:
{
"ok": true,
"address": "0x5678...efgh",
"primary_name": "nftprof",
"record": {
"name": "nftprof",
"token_id": 42,
"owner": "0x1234...abcd",
"spatial_binding": "0x5678...efgh",
"tier": "high",
"bound": true,
"forward_url": "https://pentagon.games/acc/nftprof"
}
}
Resolution priority:
- Spatial binding (the address the name explicitly resolves to)
- Token ownership (the wallet that holds the name NFT)
This is the key endpoint for wallet integration. When displaying a Pentagon Chain address, call this to show @nftprof instead of 0x5678....
Names by Address Key Recommended
Get all PNS names owned by or bound to an address.
GET /api/v1/names/:address
Response:
{
"ok": true,
"address": "0x1234...abcd",
"count": 3,
"names": [
{ "name": "nftprof", "token_id": 42, "tier": "high", "bound": true, ... },
{ "name": "pentagon", "token_id": 1, "tier": "super_high", "bound": false, ... },
{ "name": "gunnies", "token_id": 2, "tier": "super_high", "bound": false, ... }
]
}
List All Names Key Recommended
Paginated list of all minted PNS names.
GET /api/v1/names?offset=0&limit=50
| Query Param | Default | Description |
|---|
offset | 0 | Starting index |
limit | 50 | Max 100 per page |
Registry Stats No Rate Limit
GET /api/v1/stats
{
"ok": true,
"total_minted": 91,
"indexed": 91,
"unique_owners": 12,
"bound_names": 45,
"tiers": { "super_high": 10, "high": 35, "medium": 46 },
"contract": "0xf97EB9f8293D1FD5587a809Eb74518c300738d07",
"chain": "Pentagon Chain",
"chain_id": 3344
}
Integration Guide
Wallet Integration (showing @names instead of 0x addresses)
// JavaScript — resolve address to display name
async function resolvePNS(address) {
const resp = await fetch(`https://id.peg.gg/api/v1/reverse/${address}?key=YOUR_KEY`);
const data = await resp.json();
if (data.ok) return `@${data.primary_name}`;
return address; // fallback to raw address
}
// Usage in your wallet UI
const displayName = await resolvePNS("0x5678...");
// → "@nftprof"
Send-to-Name (resolving @name to address before sending TX)
// JavaScript — resolve name to send address
async function resolveNameToAddress(name) {
const clean = name.replace(/^@/, '').replace(/\.peg\.gg$/, '');
const resp = await fetch(`https://id.peg.gg/api/v1/resolve/${clean}?key=YOUR_KEY`);
const data = await resp.json();
if (data.ok && data.record.spatial_binding) {
return data.record.spatial_binding; // the bound address
}
if (data.ok) {
return data.record.owner; // fallback to owner
}
throw new Error('Name not found');
}
// Usage: send 1 PC to @nftprof
const to = await resolveNameToAddress("nftprof");
// → "0x5678...efgh"
On-Chain Resolution (no API needed)
You can also resolve names directly from the smart contract:
// Solidity — resolve name to address on-chain
interface IPegNameRegistry {
function nameExists(string calldata name) external view returns (bool);
function tokenOfName(string calldata name) external view returns (uint256);
function spatialBinding(uint256 tokenId) external view returns (address);
function ownerOf(uint256 tokenId) external view returns (address);
}
contract MyContract {
IPegNameRegistry pns = IPegNameRegistry(0xf97EB9f8293D1FD5587a809Eb74518c300738d07);
function resolveToAddress(string calldata name) external view returns (address) {
require(pns.nameExists(name), "Name not found");
uint256 tokenId = pns.tokenOfName(name);
address spatial = pns.spatialBinding(tokenId);
return spatial != address(0) ? spatial : pns.ownerOf(tokenId);
}
}
Pentagon Chain RPC
| Network | Value |
|---|
| Chain Name | Pentagon Chain |
| RPC URL | https://rpc.pentagon.games |
| Chain ID | 3344 |
| Symbol | PC |
| Explorer | https://explorer.pentagon.games |
| PNS Contract | 0xf97EB9f8293D1FD5587a809Eb74518c300738d07 |
Error Responses
| Status | Error Code | Description |
|---|
| 400 | invalid_name | Name parameter missing or invalid |
| 400 | invalid_address | Address is not a valid 0x format |
| 401 | invalid_api_key | API key not found or disabled |
| 404 | not_found | Name or address has no PNS record |
| 429 | rate_limited | Public rate limit exceeded (1/min) |
| 500 | internal | Server error |