x403 protocol
HTTP-Native Wallet Authentication for Solana
AutoIncentive leverages the OpenKitx403 protocol to provide secure, stateless wallet authentication for our platform. This HTTP-native authentication system enables seamless wallet-based access control without requiring custom protocols or account secrets.
What is x403?
OpenKitx403 is an open-source, HTTP-native wallet authentication protocol for Solana that uses standard HTTP 403 responses as the authentication primitive. It provides:
HTTP-Native - Uses standard HTTP 403 challenges
Stateless - No server-side sessions required
Secure - Ed25519 signature verification with replay protection
Easy Integration - Drop-in middleware for Express, Fastify, and FastAPI
AI-Friendly - LangChain integration and autonomous agent support
Token-Gating Ready - Built-in support for NFT/token requirements
How AutoIncentive Uses x403
AutoIncentive implements x403 authentication on our servers, enabling secure wallet-based access to our platform services. Both our server infrastructure and AI agents run on AutoIncentive servers, providing a unified authentication experience.
Benefits for Clients
No Account Management
Users don't need to create accounts, remember passwords, or manage account secrets. Authentication is handled entirely through their Solana wallet.
Benefits:
✅ No registration process
✅ No password management
✅ No account recovery needed
✅ Wallet is your identity
Stateless Authentication
x403 is completely stateless - no server-side sessions required. This means:
Scalability - No session storage needed
Performance - Faster authentication
Reliability - No session expiration issues
Simplicity - Easier to implement and maintain
Secure by Design
x403 uses cryptographic signatures (Ed25519) for authentication:
Replay Protection - Nonce-based challenge system
Method/Path Binding - Prevents cross-endpoint replay
Short-Lived Challenges - 60-second default TTL
Clock Skew Tolerance - Handles time differences
Origin Binding - Optional additional security layer
Seamless User Experience
Authentication happens automatically through wallet interactions:
User accesses protected resource
Server responds with 403 + challenge
Wallet prompts for signature
User signs once
Access granted automatically
Token-Gating Support
x403 supports token-gating, allowing AutoIncentive to restrict access based on NFT or token holdings:
NFT Requirements - Access only for NFT holders
Token Requirements - Minimum token balance requirements
Custom Logic - Implement any gating logic
Dynamic Verification - Real-time token checking
Use Cases
AI Holders Platform
Primary Use Case: autoincentive.online/aitholders
The AI Holders platform uses x403 authentication to provide exclusive access to AI agent holders.
Agent Authentication
AI agents running on AutoIncentive servers use x403 for secure API access.
Platform Services
AutoIncentive uses x403 to protect various platform services:
Protected Resources:
Dashboard Access — Wallet-authenticated dashboard
API Endpoints — Secure API access
Agent Management — Agent configuration interfaces
Analytics — Protected analytics dashboards
Settings — Platform configuration access
Technical Implementation
Server-Side Integration
AutoIncentive implements x403 on our servers using the official SDKs.
Express/Fastify (TypeScript)
import { createOpenKit403, inMemoryLRU } from '@openkitx403/server';
const openkit = createOpenKit403({
issuer: 'autoincentive-v1',
audience: 'https://autoincentive.online',
ttlSeconds: 60,
bindMethodPath: true,
replayStore: inMemoryLRU(),
tokenGate: async (address: string) => {
// Check if wallet holds required token/NFT
return await checkTokenHolding(address);
}
});
app.use(openkit.middleware());
app.get('/protected', (req, res) => {
const user = req.openkitx403User;
res.json({
message: 'Authenticated!',
wallet: user.address
});
});FastAPI (Python)
from fastapi import FastAPI, Depends
from openkitx403 import OpenKit403Middleware, require_openkitx403_user
app = FastAPI()
app.add_middleware(
OpenKit403Middleware,
audience="https://autoincentive.online",
issuer="autoincentive-v1",
ttl_seconds=60,
bind_method_path=True,
replay_backend="memory",
token_gate=check_token_holding # Custom function
)
@app.get("/protected")
async def protected(user=Depends(require_openkitx403_user)):
return {
"message": "Authenticated!",
"wallet": user.address
}Client-Side Integration
Users interact with x403-protected resources through their wallets.
Browser Client
import { OpenKit403Client } from '@openkitx403/client';
const client = new OpenKit403Client();
// Connect wallet
await client.connect('phantom');
// Authenticate with protected resource
const response = await client.authenticate({
resource: 'https://autoincentive.online/aitholders',
method: 'GET'
});
if (response.ok) {
const data = await response.json();
console.log('✅ Authenticated as:', client.getAddress());
}Authentication Process
Step 1: Initial Request
GET /aitholders
Host: autoincentive.onlineStep 2: Challenge Response
HTTP/1.1 403 Forbidden
WWW-Authenticate: OpenKitx403 challenge="...",
issuer="autoincentive-v1",
audience="https://autoincentive.online"Step 3: Wallet Signature
User's wallet signs the challenge using Ed25519.
Step 4: Authenticated Request
GET /aitholders
Host: autoincentive.online
Authorization: OpenKitx403 signature="...",
challenge="...",
address="..."Step 5: Success Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"message": "Welcome, AI Holder!",
"wallet": "..."
}Security Features
Replay Protection
x403 prevents replay attacks through:
Nonce Store - Tracks used challenges
TTL Expiration - Challenges expire after 60 seconds
Method/Path Binding - Challenges tied to specific endpoints
One-Time Use - Each challenge can only be used once
Signature Verification
Ed25519 Cryptography - Industry-standard signature algorithm
Wallet Verification - Signature verified against wallet address
Challenge Binding - Signature tied to specific challenge
Timestamp Validation - Clock skew tolerance built-in
Token Gating
AutoIncentive implements token-gating for exclusive access:
const tokenGate = async (address: string) => {
// Check if wallet holds required NFT
const hasNFT = await checkNFTOwnership(address, requiredNFT);
// Check if wallet holds required token
const hasToken = await checkTokenBalance(address, minBalance);
return hasNFT || hasToken;
};AI Agent Integration
AutoIncentive's AI agents use x403 for secure authentication.
LangChain Integration
import { SolanaWalletAuthTool } from '@openkitx403/langchain';
import { initializeAgentExecutorWithOptions } from 'langchain/agents';
const tools = [
new SolanaWalletAuthTool({
resource: 'https://autoincentive.online/api',
wallet: agentWallet
})
];
const executor = await initializeAgentExecutorWithOptions(
tools,
model,
{ agentType: "zero-shot-react-description" }
);
const result = await executor.call({
input: "Authenticate and access protected API"
});Supported Wallets
AutoIncentive supports all major Solana wallets through x403:
Phantom
✅
⚠️ Via WalletConnect
Supported
Backpack
✅
❌
Supported
Solflare
✅
⚠️ Via WalletConnect
Supported
Any WalletConnect-compatible wallet
✅
✅
Supported
Server Infrastructure
AutoIncentive Servers
Dedicated Servers - Full control over authentication
High Availability - Redundant server infrastructure
Performance - Optimized for fast authentication
Security - Enterprise-grade security measures
Bot Infrastructure
Server-Side Execution - Bots run on our infrastructure
x403 Authentication - Bots authenticate using x403
Secure Communication - All bot-server communication secured
Scalable - Handles multiple concurrent bots
Use Case: AI Holders Platform
The AI Holders platform demonstrates x403 authentication in action.
Features
Exclusive Access — Only wallets holding specific AI agent NFTs/tokens can access
Automatic verification on each request
No manual whitelisting needed
Seamless Authentication — Users connect wallet once; automatic authentication for subsequent requests; no account creation required
Real-Time Verification — Token holdings checked on each request; up-to-date access control
Secure Access — Cryptographic proof of ownership; transparent verification process
Implementation
// Server-side token gating
const openkit = createOpenKit403({
issuer: 'autoincentive-v1',
audience: 'https://autoincentive.online',
tokenGate: async (address: string) => {
// Check for AI agent NFT
const hasAgentNFT = await checkAgentNFT(address);
// Check for minimum token balance
const hasTokens = await checkTokenBalance(address, 1000);
return hasAgentNFT || hasTokens;
}
});
// Protected route
app.get('/aitholders', openkit.middleware(), (req, res) => {
const user = req.openkitx403User;
res.json({
message: 'Welcome, AI Holder!',
wallet: user.address,
access: 'granted'
});
});Advantages Over Traditional Authentication
Traditional Authentication Issues
❌ Requires account creation
❌ Password management complexity
❌ Session management overhead
❌ Account recovery processes
❌ Centralized user database
x403 Benefits
✅ Wallet-based (no accounts)
✅ No passwords needed
✅ Stateless (no sessions)
✅ No recovery needed
✅ Decentralized identity
Getting Started
For AI Agents
Configure Agent Wallet
Set up agent wallet
Fund if needed for operations
Configure authentication
Integrate x403 Client
Use x403 client SDK
Handle authentication flow
Store authentication tokens
Make Authenticated Requests
Include x403 authorization headers
Handle authentication errors
Re-authenticate when needed
Resources
Official x403 Resources
AutoIncentive Integration
AI Holders Platform - Live x403 implementation
Communication System - Related services
AI Agents - Agent authentication
Platform Features - Platform capabilities
Community Resources
Security & Best Practices
Security Recommendations
✅ Always verify signatures server-side
✅ Use short TTL for challenges (60s default)
✅ Implement replay protection
✅ Use token gating for exclusive access
✅ Monitor authentication attempts
✅ Handle clock skew properly
Best Practices
Use official x403 SDKs
Implement proper error handling
Log authentication events
Test in development environment
Monitor authentication success rates
Keep server infrastructure secure
FAQ
Last updated