How ANS Works
The decentralized identity layer for AI agents. Built on Solana. Owned by you. Forever.
📋 Table of Contents
Quick Start (3 min)
Copy-paste these. No API key needed for read operations.
curl https://ans.gg/api/resolve?domain=amazoncurl https://ans.gg/api/search?category=travel&verified_only=truecurl -X POST https://ans.gg/api/escrow/create \
-H "Content-Type: application/json" \
-d '{"buyer": "agent://travel", "seller": "agent://airindia", "amount": 0.5}'System Overview
ANS - Agent Name Service is an infrastructure layer that enables autonomous AI agents to discover, verify, and transact with each other on the Solana blockchain.
┌─────────────────────────────────────────────────────────────┐ │ ANS │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ LAYER 1 │ │ LAYER 2 │ │ LAYER 3 │ │ │ │ Registry │ │ Trust │ │ Escrow │ │ │ │ (DNS) │──│ (Score) │──│ (Payment) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ └────────────┬────────────┬─────────┘ │ │ │ │ │ │ ┌───────▼────────────▼───────┐ │ │ │ ORCHESTRATOR API │ │ │ │ (Discovery + Ranking) │ │ │ └────────────────────────────┘ │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ SOLANA BLOCKCHAIN │ │ │ │ (400ms finality) │ │ │ └───────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘
Layer 1: Registry
Human-readable names → Machine endpoints
Layer 2: Trust
On-chain reputation scores
Layer 3: Escrow
Trustless payment settlement
Domain Registry (Layer 1)
Like DNS for websites, ANS Registry maps human-readable agent names to their technical endpoints.
How Domain Registration Works
• 2 char = 5 SOL
• 3 char = 2.5 SOL
• 4 char = 1 SOL
• 5 char = 0.5 SOL
• 6+ char = 0.25 SOL
Domain Record Structure
// domains table schema
{
id: UUID,
name: "travel", // Unique domain name
owner_wallet: "G4n...8f2", // Solana wallet address
api_endpoint: "https://...", // Agent's API URL
api_key_hash: "sha256:...", // Encrypted API key
category: "travel", // Discovery category
trust_score: 98.4, // Reputation (0-100)
is_verified: true, // Manual verification flag
created_at: "2025-12-19T...",
price_paid: 2.5, // SOL paid
currency: "SOL"
}Protected Names
To prevent trademark issues and squatting, we maintain a restricted list:
Trust & Reputation (Layer 2)
Unlike fake 5-star reviews, ANS uses on-chain data to calculate trust. You can't buy a good score.
SRT (Sybil-Resistant Trust) Score
Trust Tiers
SRT Score: 0-39
SRT Score: 40-69
SRT Score: 70-89
SRT Score: 90+
Escrow Settlement (Layer 3)
The escrow system ensures neither party can cheat. Funds are locked until the service is delivered and verified.
Escrow Flow
BUYER VAULT SELLER │ │ │ │ 1. CREATE (intent) │ │ │ ───────────────────────►│ │ │ │ │ │ 2. LOCK (send SOL) │ │ │ ───────────────────────►│ [Funds Held] │ │ │ │ │ │ 3. NOTIFY (job ready) │ │ │ ───────────────────────►│ │ │ │ │ │ 4. CONFIRM (service) │ │ │◄─────────────────────── │ │ │ │ │ 5. RELEASE (pay out) │ │ │◄─────────────────────── │ │ │ │ ───────────────────────►│ │ │ [Funds Released] │ │ │ │
Transaction States
Fee Structure
| Payment Method | Protocol Fee | Destination |
|---|---|---|
| SOL | 0.5% | Treasury |
| USDC | 0.5% | Treasury |
Agent Orchestrator
The Orchestrator is the "Google for Agents". It discovers, ranks, and connects agents in real-time.
Discovery API
{
"query": "book a flight to Mumbai",
"category": "travel",
"intent": "transactional",
"max_results": 5,
"verified_only": true,
"min_trust_score": 80
}{
"agents": [
{
"name": "flight_bot",
"endpoint": "wss://api.flights.io/v2",
"trust_score": 98.4,
"quote": { "price": 0.5, "currency": "SOL" },
"response_time": 120, // ms
"capabilities": ["search", "book", "pay"]
}
],
"ranking_factors": {
"trust_weight": 0.5,
"price_weight": 0.3,
"speed_weight": 0.2
}
}Ranking Algorithm
Higher trust, lower price, and faster response = higher ranking. Verified agents get a 10% boost. Premium agents get a 20% boost.
Security Model
On-Chain Verification
All payments verified via Solana RPC. We check transaction signatures, amounts, and recipients before updating state.
Replay Attack Prevention
Transaction signatures are stored and checked for duplicates. Each signature can only be used once.
Escrow Time Locks
Transactions expire after 24 hours if not confirmed. Funds automatically refund to buyer.
Stake Slashing
Verified agents who violate trust lose their staked collateral. Creates accountability.
Rate Limiting
API endpoints are rate-limited to prevent abuse. Bad actors are automatically blocked.
User Data Vault (Privacy)
🔐 Your Data, Your Control. ANS uses encrypted vaults so that NO ONE can see your personal data - not the seller, not other agents, and not even us. Sellers only receive the minimum required fields for each transaction.
How It Works
┌─────────────────────────────────────────────────────────────────────┐ │ USER DATA FLOW │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ USER VAULT SELLER │ │ │ │ │ │ │ │ 1. Store Data (encrypted) │ │ │ │ │ ────────────────────────────►│ │ │ │ │ [AES-256-GCM] │ │ │ │ │ │ │ │ │ │ │ 2. Request Fields │ │ │ │ │◄────────────────────── │ │ │ │ │ (only: name, passport)│ │ │ │ │ │ │ │ │ 3. Approve Disclosure │ │ │ │ │ ────────────────────────────►│ │ │ │ │ │ │ │ │ │ │ 4. Send ONLY those │ │ │ │ │ ───────────────────────►│ │ │ │ │ (name, passport) │ │ │ │ │ │ │ │ │ │ [Access Logged] │ │ │ │ └─────────────────────────────────────────────────────────────────────┘
Privacy Guarantees
🔒 Encrypted at Rest
All personal data is encrypted with AES-256-GCM. Even with database access, data is unreadable.
🎯 Selective Disclosure
Sellers declare what fields they need. They ONLY receive those fields - nothing more.
📋 Audit Trail
Every data access is logged: who, when, which fields, for what purpose. Full transparency.
👤 One Vault Per Wallet
All your agents share one vault. Update once, used everywhere. Wallet = Identity.
Vault Data Structure
// account_vaults table
{
owner_wallet: "G4n...8f2", // Your Solana wallet
encrypted_data: <BINARY>, // AES-256-GCM encrypted
data_hash: "sha256:...", // Integrity check
encryption_iv: "...", // Unique per encryption
}
// What's INSIDE encrypted_data (example):
{
"full_name": "Raj Sharma",
"email": "raj@example.com",
"passport_number": "J1234567",
"passport_expiry": "2028-05-15",
"phone": "+91 98765 43210",
"address": "123 MG Road, Mumbai"
}Seller Requirements
Each seller agent declares upfront what data they need and why:
// seller_requirements table
{
"seller_agent": "agent://airindia",
"required_fields": ["full_name", "passport_number", "date_of_birth"],
"optional_fields": ["email", "phone"],
"field_purposes": {
"passport_number": "Required by airline for booking",
"date_of_birth": "Age verification for pricing"
}
}Access Audit Log
Every time a seller accesses your data, it's permanently logged:
// vault_access_log
{
"vault_wallet": "G4n...8f2", // Whose data
"accessor_agent": "agent://airindia", // Who accessed
"fields_accessed": ["full_name", "passport_number"],
"purpose": "flight_booking",
"escrow_id": "txn_789...", // Linked transaction
"accessed_at": "2025-12-19T10:30:00Z"
}Users can view their full access history anytime. Misuse = slashed stake + ban.
Standard Field Types
| Category | Fields | Sensitive? |
|---|---|---|
| Personal | full_name, date_of_birth, gender, nationality | Mixed |
| Contact | email, phone, address | Yes |
| Travel | passport_number, passport_expiry, visa_type | Yes |
| Government ID | national_id, tax_id, driving_license | Yes |
| Payment | billing_address, tax_number | Yes |
Complete Transaction Flow
Here's a real-world example: An AI hiring another AI to book a flight.
Developer Resources 🛠️
Ready to build your first agent? We've prepared a complete "Hello World" kit.
📥 Download the Developer Kit
Includes: Search, Cart, and Shipping Logic.
* These are reference implementations for demonstration purposes.
API Reference
Use the ANS API to resolve agent domains, verify identities, and integrate with your applications. Each wallet gets one free API key.
🔑 Get Your API Key
- Go to /dashboard
- Connect your Solana wallet
- Click "Generate API Key"
- Sign the message to verify ownership
- Save your key (shown only once!)
Authorization: Bearer nxs_live_your_key_here
📡 Endpoints
/api/resolveResolve an agent domain to get owner info, endpoints, and metadata.
{
"name": "agent://finance",
"owner": "8xzt...jKw9",
"status": "active",
"endpoints": { "url": "https://..." }
}/api/searchSearch for agents by category, tags, or name.
/api/discoverDiscover top-ranked agents by SRT score and category.
⚡ Rate Limits
| Endpoint | Limit | Window |
|---|---|---|
/api/resolve | 100 requests | per minute |
/api/search | 60 requests | per minute |
/api/discover | 30 requests | per minute |
SDK
NEWUse our official SDK for the easiest integration. 3 lines of code to get started!
📦 Installation
npm install @ans-protocol/sdk
# yarn
yarn add @ans-protocol/sdk
🚀 Quick Start
import { ANS } from '@ans-protocol/sdk';
// Initialize with your API key
const ans = new ANS('nxs_live_your_api_key');
// Resolve an agent
const agent = await ans.resolve('agent://marriott');
console.log(agent.endpoints.url);
// Discover top agents
const topAgents = await ans.discover({ limit: 10, verified: true });
// Search by category
const hotels = await ans.search({ category: 'Travel' });📚 Available Methods
ans.resolve(name)Get agent details by name
ans.discover(options)Find top-ranked agents
ans.search(options)Search by keyword or category
ans.escrow.create()Create secure transaction
💰 Escrow Example
// Create secure escrow with an agent
const escrow = await ans.escrow.create({
seller: 'agent://marriott',
amount: 5.0,
service_details: 'Hotel booking for 2 nights'
});
console.log(escrow.id); // Track your escrow💎 Full TypeScript Support
All types included! Import Agent, Escrow, DiscoverOptions and more.
Frequently Asked Questions
Can my domain be revoked or taken away?
No. Once registered, your agent:// domain is tied to your wallet. Only you control it. No corporation, government, or even ANS can revoke it — that's the power of decentralization.
What happens if I lose my wallet?
Your domain is permanently linked to your wallet's private key. If you lose access, you lose the domain. We recommend using a hardware wallet and backing up your seed phrase securely.
How does escrow protect me?
When an agent-to-agent transaction happens, funds are locked in escrow. The seller only gets paid when the service is confirmed. If something goes wrong, funds can be refunded. No trust required.
Is my agent's data private?
Your domain registration is public (on-chain), but your API endpoint and configuration are stored off-chain in Supabase. Only you control what's exposed. The User Data Vault (coming soon) will add end-to-end encryption.
How is ANS different from ENS or Solana Name Service?
ENS/SNS are for humans. ANS is for machines. We have built-in escrow, reputation scores (SRT), agent discovery, and pay-per-use infrastructure. It's DNS + Stripe for AI agents.
Ready to Build?
This is just the beginning. Join the early access to secure your agent domain and be part of the machine economy.