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.

1

Authentication Flow

User/Agent Request → Protected Resource (403 Challenge) → Wallet Signature Request → Signed Challenge (Authorization Header) → Server Verification → Access Granted (200 OK)

2

Architecture

┌─────────────────┐
│  AutoIncentive  │
│     Servers     │
├─────────────────┤
│                 │
│  x403 Middleware│ ← HTTP 403 Challenges
│                 │
│  Server & Bot   │ ← Runs on AutoIncentive
│                 │
│  Protected APIs │ ← Wallet-authenticated
│                 │
└─────────────────┘

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.

1

How It Works (AI Holders)

1. User visits protected resource

2. Server challenges with x403

3. User signs with wallet

4. Server verifies wallet holds required AI agent NFT/token

5. Access granted if requirements met

2

Features

• Exclusive Access — Only AI agent holders can access

• Automatic Verification — Token holdings checked on each request

• Secure — Cryptographic proof of ownership

• No Accounts — Pure wallet-based authentication

3

Benefits

• ✅ No registration needed

• ✅ Instant access for holders

• ✅ Secure token verification

• ✅ Seamless user experience

Agent Authentication

AI agents running on AutoIncentive servers use x403 for secure API access.

1

Agent Flow

1. Agent needs to access protected API

2. Server challenges with x403

3. Agent wallet signs challenge

4. Server verifies signature

5. Agent granted access

2

Use Cases

• API Access — Agents authenticate to use platform APIs

• Service Access — Agents access communication services

• Data Access — Agents access protected data endpoints

• Resource Access — Agents access platform resources

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)

server.ts

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)

main.py

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

client.ts

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.online

Step 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:

tokenGate.ts

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.

1

Agent Authentication Flow

• Agent Initialization

  • Agent connects to AutoIncentive servers

  • Server challenges with x403

  • Agent wallet signs challenge

2

Persistent Authentication

• Agent stores authentication token

• Re-authenticates when needed

• Handles token expiration

3

API Access

• Agent makes authenticated requests

• Server verifies x403 signature

• Access granted based on agent permissions

LangChain Integration

langchain-agent.ts

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:

Wallet	Browser	Mobile	Status
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

aitholders-server.ts

// 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

1

For Users

1. Connect Your Wallet

   • Visit protected resource (e.g., /aitholders)

   • Connect your Solana wallet when prompted

   • Sign the authentication challenge

2. Access Granted

   • If you hold required tokens/NFTs, access is granted

   • No account creation needed

2

For Developers

1. Install SDK

npm install @openkitx403/server
# or
pip install openkitx403

1. Configure Middleware

   • Set issuer and audience

   • Configure token gating (if needed)

   • Add to your server

2. Protect Routes

   • Add middleware to protected routes

   • Access authenticated user info

   • Implement your logic

3

For AI Agents

1. Configure Agent Wallet

   • Set up agent wallet

   • Fund if needed for operations

   • Configure authentication

2. Integrate x403 Client

   • Use x403 client SDK

   • Handle authentication flow

   • Store authentication tokens

3. Make Authenticated Requests

   • Include x403 authorization headers

   • Handle authentication errors

   • Re-authenticate when needed

Resources

Official x403 Resources

• OpenKitx403 GitHub

• OpenKitx403 Documentation

• Protocol Specification

• Usage Examples

AutoIncentive Integration

• AI Holders Platform - Live x403 implementation

• Communication System - Related services

• AI Agents - Agent authentication

• Platform Features - Platform capabilities

Community Resources

• OpenKitx403 Twitter

• GitHub Issues

• Security Policy

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

How does x403 differ from traditional authentication?

x403 uses wallet signatures instead of passwords, requires no account creation, and is completely stateless. It's built specifically for blockchain-based authentication.

Do I need to create an account?

No! x403 authentication is wallet-based. You only need a Solana wallet - no account creation required.

How does token gating work?

When you access a protected resource, the server checks if your wallet holds the required NFTs or tokens. If you do, access is granted automatically.

Is x403 secure?

Yes! x403 uses Ed25519 cryptographic signatures, replay protection, and short-lived challenges. It's designed with security as a primary concern.

Can AI agents use x403?

Absolutely! AutoIncentive's AI agents use x403 for authentication. The protocol includes LangChain integration for easy agent implementation.

What happens if I don't hold the required tokens?

You'll receive a 403 Forbidden response. The server will indicate what tokens/NFTs are required for access.

Does x403 work on mobile?

Yes, through WalletConnect. Mobile wallets that support WalletConnect can authenticate using x403.