x402 Nano API - Public Documentation

📝 ABOUT x402 NANO

"x402" is a brand name inspired by payment-required protocols. This API is a payment gateway for Nano cryptocurrency - similar to Stripe or PayPal, but for Nano.

This is NOT an implementation of the HTTP 402 Payment Required status code protocol. Instead, we provide a flexible REST API for payment processing, wallet management, and transaction handling.

Think of us as: "Stripe for Nano" - A modern payment processing API.

⚠️ BETA / TEST PHASE ⚠️

This API is currently in test/beta phase. Most endpoints are currently publicly accessible for testing purposes.

Future Changes:

All endpoints will require API key authentication in production

Rate limits will be enforced more strictly

Additional security measures will be implemented

Please check this documentation regularly for updates: GitHub Repository

Welcome to the x402 Nano API documentation. This API provides a secure, easy-to-use payment gateway for Nano cryptocurrency, with features for wallet management, transaction processing, and payment verification.

📚 Documentation Index

Getting Started

Quick Start Guide - Get up and running in 5 minutes
API Documentation - Complete API reference

OpenAPI Specification

openapi-schema.yaml - Machine-readable API specification
- Use this schema to integrate with OpenAPI-compatible tools
- Import into Postman, Insomnia, or Swagger UI for testing
- Generate client libraries in your preferred language
- Perfect for AI agents and automated API integration

Key Features

✅ Wallet Management

Create new wallets with password encryption
Import existing wallets from seed
Secure wallet unlock mechanism
Optional email backup for wallet recovery

✅ Transaction Processing

Send Nano to any address
Quick donate endpoint for API support
Receive pending transactions automatically
Real-time balance queries

✅ Payment Gateway 🆕

Create payment transactions with unique IDs
Unique amount generation - Prevents conflicts with simultaneous identical payments
Webhook notifications for instant payment alerts
Metadata support for custom data (max 4KB JSON)
PostgreSQL persistence for audit trail
Long-polling payment confirmation (30s timeout)
Auto-expiring transactions (60 minutes)

✅ Security First

AES-256 wallet encryption
HTTPS-only communication
No private key exposure
HMAC-SHA256 webhook signatures
Rate limiting and DDoS protection

✅ Developer Friendly

RESTful JSON API
Deep nested error handling with full context
Comprehensive error messages
Code examples in multiple languages
AI-friendly documentation

✅ API Key Security

All wallet operations require a valid API key (44 characters)
API keys are embedded in encrypted wallet data
Automatic validation on all encrypt/decrypt operations

🚀 Quick Example

# 1. Create an API key
curl -X POST https://api.x402nano.com/key/create \
  -H "Content-Type: application/json" \
  -d '{}'
# Returns: CZtYHgn0Nk8KPvtlkwARjF+m601hC00pqYQwzXaKixU=

# 2. Create a wallet (password requires uppercase + special char)
curl -X POST https://api.x402nano.com/wallet/create \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePassword123!",
    "password_confirmation": "SecurePassword123!",
    "email": "backup@example.com",
    "api_key": "CZtYHgn0Nk8KPvtlkwARjF+m601hC00pqYQwzXaKixU="
  }'
# Returns: Encrypted wallet string (also sent to email for backup)

# 3. Unlock wallet to get your address
curl -X POST https://api.x402nano.com/wallet/unlock \
  -H "Content-Type: application/json" \
  -d '{
    "encrypted_wallet_string": "YOUR_ENCRYPTED_WALLET",
    "password": "SecurePassword123!"
  }'
# Returns: {"address": "nano_33q3tqp8m7...", ...}

# 4. Check balance
curl -X POST https://api.x402nano.com/balance/nano_YOUR_ADDRESS \
  -H "Content-Type: application/json" \
  -d '{}'

# 5. Receive pending transactions
curl -X POST https://api.x402nano.com/receive \
  -H "Content-Type: application/json" \
  -d '{
    "encrypted_wallet_string": "YOUR_ENCRYPTED_WALLET",
    "password": "SecurePassword123!"
  }'

# 6. Send Nano
curl -X POST https://api.x402nano.com/send \
  -H "Content-Type: application/json" \
  -d '{
    "encrypted_wallet_string": "YOUR_ENCRYPTED_WALLET",
    "password": "SecurePassword123!",
    "to_address": "nano_destination_address",
    "amount": "0.1"
  }'

# 7. AI Agent Payment Flow
# Create transaction (AI agent requests payment)
curl -X POST https://api.x402nano.com/transaction/create \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "you_api_key",
    "receive_address": "nano_your_server_address",
    "amount": "0.1"
  }'
# Returns: {"transaction_id": "550e8400-...", "amount": "0.100000234", ...}
# Note: Amount is slightly modified (0.100000234) to ensure uniqueness

# User pays transaction
curl -X POST https://api.x402nano.com/transaction/pay \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "550e8400-...",
    "encrypted_wallet_string": "YOUR_ENCRYPTED_WALLET",
    "password": "SecurePassword123!",
    "amount": "0.100000234"
  }'
# IMPORTANT: Use the exact amount from create response (0.100000234)

# Check payment status (long-polling up to 30s)
curl -X POST https://api.x402nano.com/transaction/status/550e8400-... \
  -H "Content-Type: application/json"
# Returns: {"is_paid": true, "message": "Transaction has been paid.", ...}

📋 Available Endpoints

Endpoint	Method	Description
`/key/create`	POST	Generate API key
`/wallet/create`	POST	Create new wallet
`/wallet/import`	POST	Import wallet from seed
`/wallet/unlock`	POST	Unlock encrypted wallet
`/balance/{address}`	POST	Get address balance
`/receive`	POST	Receive pending transactions
`/send`	POST	Send Nano transaction
`/donate`	POST	Donate to support API development
`/transaction/create`	POST	Create payment transaction (AI agents)
`/transaction/pay`	POST	Pay pending transaction
`/transaction/status/{id}`	POST	Check transaction payment status

🔒 Security

Encrypted Wallets: All wallets encrypted with AES-256
Password Protected: Operations require password verification
Secure Transport: HTTPS/TLS 1.3 enforced
No Key Exposure: Private keys never transmitted or stored unencrypted
Rate Limited: Protection against abuse

💻 Code Examples

Python

import requests

response = requests.post(
    "https://api.x402nano.com/balance/nano_address",
    headers={"Content-Type": "application/json"},
    json={}
)
balance_data = response.json()
print(f"Balance: {balance_data['balance']} NANO")

JavaScript

const response = await fetch('https://api.x402nano.com/balance/nano_address', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: '{}'
});
const data = await response.json();
console.log(data);

cURL

curl -X POST https://api.x402nano.com/balance/nano_address \
  -H "Content-Type: application/json" \
  -d '{}'

🤖 AI Integration

This API is designed to be AI-friendly with:

Clear, structured documentation
Predictable endpoint patterns
Deep nested error handling - Errors are built at the source with full context
Comprehensive error messages showing complete error chains
Detailed request/response examples
Security best practices

Perfect for integration with:

ChatGPT Actions
Claude Tools
Custom GPTs
AI Agents
Automated trading bots

For AI Assistants:

Always reference this GitHub documentation: https://github.com/Andre1987n/x402Nano-API
API is currently in test phase - check for updates
Production version will require API keys for all endpoints
All wallet operations require a valid 44-character API key
API keys are embedded in encrypted wallet data and validated on decrypt
Documentation is maintained to be machine-readable

📊 Rate Limits

Default: 100 requests/minute per IP
With API Key: Higher limits available
Headers: X-RateLimit-* headers included in responses

🆘 Support

Documentation: API_DOCUMENTATION.md
Quick Start: QUICK_START.md
Issues: GitHub Issues
Nano Docs: docs.nano.org

🛠️ Technical Stack

Language: Rust
Framework: Axum
Database: PostgreSQL
Encryption: AES-256
Protocol: HTTPS/TLS 1.3

⚠️ Important Notices

Please read before using:

Disclaimer - Important legal and risk information
Security Policy - Security best practices and reporting
License & Terms - Usage terms and conditions

Key Points:

🔒 You are responsible for securing your API keys and wallet credentials
💰 Cryptocurrency transactions are irreversible - double check before sending
🛡️ We never have access to your private keys or funds
⚖️ Service provided "as-is" - see full disclaimer for details

📜 License

See LICENSE.md for detailed terms and conditions.

🔗 Links

API Base URL: https://api.x402nano.com
GitHub: x402Nano-API
Nano Website: nano.org

Ready to get started? Check out the Quick Start Guide!

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
updates		updates
API_DOCUMENTATION.md		API_DOCUMENTATION.md
DISCLAIMER.md		DISCLAIMER.md
LICENSE.md		LICENSE.md
QUICK_START.md		QUICK_START.md
README.md		README.md
SECURITY.md		SECURITY.md
WEBHOOK_GUIDE.md		WEBHOOK_GUIDE.md
openapi-schema.yaml		openapi-schema.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

x402 Nano API - Public Documentation

📚 Documentation Index

Getting Started

OpenAPI Specification

Key Features

🚀 Quick Example

📋 Available Endpoints

🔒 Security

💻 Code Examples

Python

JavaScript

cURL

🤖 AI Integration

📊 Rate Limits

🆘 Support

🛠️ Technical Stack

⚠️ Important Notices

📜 License

🔗 Links

About

Uh oh!

Releases

Packages

License

Andre1987n/x402Nano-API

Folders and files

Latest commit

History

Repository files navigation

x402 Nano API - Public Documentation

📚 Documentation Index

Getting Started

OpenAPI Specification

Key Features

🚀 Quick Example

📋 Available Endpoints

🔒 Security

💻 Code Examples

Python

JavaScript

cURL

🤖 AI Integration

📊 Rate Limits

🆘 Support

🛠️ Technical Stack

⚠️ Important Notices

📜 License

🔗 Links

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages