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 gasless payment settled on Base. AxonOS pays the 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	Live pricing and AXGT discount for any currency

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

Step 1 — Discover the payment requirements

bash

curl -s https://desktop.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://desktop.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://desktop.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

AxonOS pays the gas

The agent wallet only needs USDC on Base. AxonOS's settlement wallet broadcasts the EIP-3009 transfer and pays the gas, so the agent wallet needs no ETH.

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)))"'

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://desktop.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://desktop.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 live pricing per currency and the AXGT discount for any wallet address:

bash

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

# ETH quote (live USD-equivalent, AXGT discount applied if holding)
curl "https://desktop.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://desktop.axonos.io/.well-known/x402

# Smoke-test the 402 (no funds needed)
curl -s -D - -o /dev/null \
  "https://desktop.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.