Agentic access via x402

AxonOS natively speaks x402 — the HTTP 402 Payment Required standard — so any off-the-shelf x402-compatible agent can discover, pay for, and SSH into a GPU session in a single automated loop, with no browser wallet and no AxonOS-specific integration code.

🔍Discovery

GET /.well-known/x402 returns a descriptor listing the available payment assets, minimum amounts, and the network chain ID.

💳Payment

A standard 402 response on /api/x402/access triggers an EIP-3009 USDC payment settled on Base. The paying agent signs an authorization but needs no ETH for gas.

🖥️SSH session

Post the payment header to /api/x402/session with an SSH public key and get back ssh_host, ssh_port, and credentials immediately.

The x402 protocol in one paragraph

x402 is a lightweight standard built on HTTP 402. A client GETs a protected resource, receives a 402 Payment Required response whose body describes what payment to make (chain, asset, amount, recipient), sends that payment on-chain, then retries the original request with an X-PAYMENT / PAYMENT-SIGNATURE header. The server verifies the on-chain settlement and, if valid, responds 200 OK with the protected resource. No AxonOS SDK needed — only a standard Ethereum account and the Coinbase x402 SDK.

Endpoint reference

Endpoint	Method	Purpose
`/.well-known/x402`	GET	Discovery descriptor — chain, asset, minimum amounts
`/api/x402/access`	GET	Main protected resource; returns 402 → pay → 200
`/api/x402/session`	POST	One-shot: pay + claim SSH session in one call
`/api/discount/quote`	GET	Current server-side pricing and eligible AXGT holder tier

Base URL: https://app.axonos.io

Step 1 — Discover the payment requirements

bash

curl -s https://app.axonos.io/.well-known/x402

Returns a JSON descriptor with the x402 version, the chain (eip155:8453 for Base mainnet, eip155:84532 for Base Sepolia testnet), the USDC contract, and the minimum deposit for 60 minutes of compute.

Step 2 — Trigger the 402

bash

curl -s -D - -o /dev/null \
  "https://app.axonos.io/api/x402/access?wallet_address=0xYOUR_AGENT_WALLET" \
  | grep -iE "HTTP/|payment-required"

The gate responds HTTP 402 with a PAYMENT-REQUIRED header and a body containing x402Version: 2, accepts[0].amount, and network. A standard x402 SDK can parse this directly.

Step 3 — Pay and get access (Python SDK)

python

import json, os, requests
from eth_account import Account
from x402.client import x402ClientSync
from x402.http import x402HTTPClientSync
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact import ExactEvmClientScheme

GATE = "https://app.axonos.io"
acct = Account.from_key(os.environ["AGENT_PRIVATE_KEY"])

client = x402ClientSync()
client.register("eip155:8453", ExactEvmClientScheme(signer=EthAccountSigner(acct)))
http = x402HTTPClientSync(client)

url = f"{GATE}/api/x402/access?wallet_address={acct.address}"

# 1. GET → 402
r1 = requests.get(url, timeout=30)
assert r1.status_code == 402

# 2. SDK signs the EIP-3009 USDC payment
add_headers, _ = http.handle_402_response(dict(r1.headers), r1.content)

# 3. Retry with payment header → 200
r2 = requests.get(url, headers=add_headers, timeout=180)
body = r2.json()
print(body)
# { "access": true, "remaining_minutes": 60.0,
#   "payment": { "verified": true, "settlement_tx_hash": "0x..." } }

Install dependencies:

bash

pip install "x402[evm]" requests eth-account

The paying agent needs no gas

The agent wallet needs USDC on Base but no ETH. Who broadcasts and pays gas depends on the operator's settlement mode, described below.

Settlement modes for operators

The gate verifies the signed EIP-3009 authorization server-side in either mode:

Self-settlement (default path): the operator must explicitly enable settlement, configure a dedicated low-balance settlement key, and fund that wallet with ETH on Base for gas. Never reuse the treasury or revenue-wallet key. The operator's settlement wallet broadcasts the transfer.
CDP facilitator (optional): the operator enables the facilitator and supplies the required CDP credentials. CDP verifies, broadcasts, and pays settlement gas.

The paying agent signs the USDC authorization in both modes and does not need ETH. Settlement keys and CDP credentials are server secrets and must never be exposed to clients or committed to source.

Step 4 — Claim an SSH GPU session

After the 402 payment is settled, post to /api/x402/session with the same payment header and your SSH public key to receive SSH credentials immediately:

python

# Generate a keypair for the agent (once, reuse across sessions)
# ssh-keygen -t ed25519 -f ./agent_key -N ""

ssh_pub = open("agent_key.pub").read().strip()
pay_header_value = list(add_headers.values())[0]

r = requests.post(
    f"{GATE}/api/x402/session",
    headers={"PAYMENT-SIGNATURE": pay_header_value, "X-Wallet-Address": acct.address},
    json={"wallet_address": acct.address, "ssh_pubkey": ssh_pub, "requested_profile": "small"},
    timeout=180,
)
d = r.json()
# { "granted": true, "ssh_host": "axonconsole.io", "ssh_port": 42017,
#   "ssh_user": "aXonian", "remaining_minutes": 59.8, "auth_token": "...",
#   "payment": { "settlement_tx_hash": "0x..." } }

Then connect:

bash

ssh -i ./agent_key -p <ssh_port> -o StrictHostKeyChecking=accept-new \
  aXonian@axonconsole.io \
  'nvidia-smi -L && python3 -c "print(sum(i*i for i in range(1_000_000)))"'

For the hosted service, axonconsole.io is only the public SSH hostname. It is not a webpage. Use the exact ssh_host, ssh_port, and host-key fingerprint returned for the session; never assume a fixed port.

Full Node.js agent example

A complete reference implementation using the official Coinbase x402-fetch SDK is available in the AxonOS repository:

bash

cd tools/x402-agent-test
npm install
AGENT_PRIVATE_KEY=0xYOUR_KEY \
AXONOS_BASE_URL=https://app.axonos.io \
node agent.mjs

The agent walks the full loop: pay → claim SSH → run commands → heartbeat → release.

Response shape reference

`GET /api/x402/access` — success (200)

json

{
  "access": true,
  "remaining_minutes": 60.0,
  "payment": {
    "verified": true,
    "credited_minutes": 60.0,
    "settlement_tx_hash": "0x..."
  }
}

`POST /api/x402/session` — success (200)

json

{
  "granted": true,
  "ssh_host": "axonconsole.io",
  "ssh_port": 42017,
  "ssh_user": "aXonian",
  "remaining_minutes": 59.8,
  "auth_token": "<token-for-heartbeat-and-release>",
  "payment": {
    "verified": true,
    "settlement_tx_hash": "0x..."
  }
}

Heartbeat and release

While a session runs the agent should send periodic heartbeats. When the workload is done, release the session so GPUs are freed and billing stops:

bash

# Release (stops billing immediately)
curl -X POST https://app.axonos.io/api/release \
  -H "Content-Type: application/json" \
  -d '{"auth_token": "<YOUR_AUTH_TOKEN>"}'

Closing SSH does not stop billing

Closing the SSH connection leaves the session container running and credits keep ticking. Always POST to /api/release when your workload completes.

Pricing and AXGT discounts

The /api/discount/quote endpoint returns current server-side pricing per currency and the AXGT discount for any wallet address:

bash

# USDC quote (~1 USDC = 60 minutes on default config)
curl "https://app.axonos.io/api/discount/quote?currency=usdc&wallet_address=0xYOUR_WALLET"

# ETH quote (server-side USD-equivalent, AXGT discount applied if eligible)
curl "https://app.axonos.io/api/discount/quote?currency=eth&wallet_address=0xYOUR_WALLET"

Agents holding AXGT in their wallet benefit from the same discount tiers as human users. See Pricing & AXGT for the full tier table.

Testing against the testnet

Use Base Sepolia for development and testing:

bash

# Discovery on testnet (register scheme under "eip155:84532")
curl -s https://app.axonos.io/.well-known/x402

# Smoke-test the 402 (no funds needed)
curl -s -D - -o /dev/null \
  "https://app.axonos.io/api/x402/access?wallet_address=0x1111111111111111111111111111111111111111" \
  | grep -iE "HTTP/|payment-required"

Fund a throwaway wallet with Base Sepolia test USDC from the Circle faucet (select Base Sepolia). AxonOS pays test gas.

Verify settlement independently

Every settlement_tx_hash from the gate is a real on-chain transaction. Confirm it on Basescan (mainnet) or Base Sepolia to verify the USDC transfer happened — independent of AxonOS's word.