VerseOS x402 Quickstart

VerseOS supports autonomous license purchases through x402 v2 on Solana.

The tested flow is:

Agent
  ↓ POST /v1/agent-licenses
VerseOS
  ↓ 402 + PAYMENT-REQUIRED
x402 client
  ↓ signs Solana payment
VerseOS/facilitator
  ↓ verifies + settles
VerseOS
  ↓ issues LIC-...
Agent
  ← 201 + PAYMENT-RESPONSE

Current environment: Solana devnet. Keep mainnet disabled until the VerseOS x402 fee/payout strategy is finalized.

Prerequisites

You need:

• Node.js 20+
• a VerseOS API key with licenses:write
• a throwaway Solana devnet wallet
• enough devnet USDC for the license
• enough devnet SOL for transaction fees if required by the client flow

Never commit or share the wallet private key.

1. Create a test project

cd C:\Users\YOU\Downloads
mkdir verseos-x402-test
cd verseos-x402-test
npm init -y

2. Install dependencies

The tested package set is:

npm install @x402/core@2.19.0 @x402/svm@2.19.0 @x402/fetch @solana/kit @scure/base

Do not use --force or --legacy-peer-deps to bypass dependency resolution.

3. Create the buyer script

New-Item -ItemType File -Name "test-x402.mjs"

Copy examples/x402-buyer.mjs from this documentation bundle into that file.

4. Set environment variables

$env:VERSEOS_API_KEY = "vos_live_YOUR_TEST_KEY"
$env:SVM_PRIVATE_KEY = "YOUR_THROWAWAY_DEVNET_BASE58_SECRET_KEY"

SVM_PRIVATE_KEY is the base58-encoded Solana secret-key bytes expected by the test client. Do not paste it into logs, source files, tickets, or chat.

5. Run the purchase

node test-x402.mjs

The client will:

1. POST the right ID to VerseOS;
2. receive 402 Payment Required;
3. decode PAYMENT-REQUIRED;
4. create and sign the Solana payment;
5. retry the same request automatically;
6. receive the issued VerseOS license.

Tested result

A successful private-beta test returned:

HTTP status: 201

with a response shaped like:

{
  "object": "agent_license",
  "x402": true,
  "quote_id": "XQ-A9B77CB8E9D7",
  "payment": {
    "status": "settled",
    "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
    "transaction": "cCNAH2krhDGfEcCVamt6GuUYMmLwMfYao7nqXfrzxciLKPcjvBnhUpmpU8EmaaHS4Aqwd7pNbfuKpanZFHCGpgN"
  },
  "license": {
    "public_id": "LIC-F40BD43BF6BC",
    "status": "active"
  },
  "already_fulfilled": false
}

The x402 settlement response also confirmed the payer, Solana transaction, and devnet network.

x402 quote semantics

Each request requires a unique Idempotency-Key.

The persisted quote binds:

• right;
• asset;
• price;
• creator payout wallet;
• license terms;
• network;
• x402 payment requirements.

Normal retry behavior reuses the stored quote rather than creating a second purchase.

Quote state:

pending -> settled -> fulfilled

If settlement succeeds but database fulfillment fails afterward, retry the same purchase with the same Idempotency-Key. VerseOS can resume from a settled quote instead of intentionally creating another payment.

Current x402 fee policy

VerseOS's normal checkout uses:

97.5% creator
2.5% VerseOS

The current x402 devnet MVP uses a single payTo address and therefore sends the full license price directly to the creator. VerseOS does not silently collect its normal 2.5% fee in this path.

Do not enable x402 mainnet until that production fee model is explicitly selected.