@tokenosdeai/a2e-agent-sdk

Wallet-rooted AI agent SDK for TokenOS DeAI. Register an agent, fund an x402 session on Solana, call OpenAI-compatible inference with atomic per-call cap enforcement.

Install

npm install @tokenosdeai/a2e-agent-sdk
# or
pnpm add @tokenosdeai/a2e-agent-sdk

Requires Node 18+ (uses native fetch).

Quickstart

import nacl from 'tweetnacl'
import { A2EAgent } from '@tokenosdeai/a2e-agent-sdk'

// 1. Generate (or load) a Solana ed25519 keypair.
const keypair = nacl.sign.keyPair()

// 2. Register. One-time per wallet; idempotent (409 on re-register).
const agent = await A2EAgent.register({ keypair, name: 'my-trading-bot' })
console.log('Save this api key:', agent.apiKey)
// agent.apiKey: 'a2e-agent-<48 hex>'

// 3. Open an x402-funded session. signPayment is your hook — wire it
//    to a Solana wallet adapter, @x402/svm-client, or any signer that
//    can produce the base64-encoded PaymentPayload for a TransferChecked.
const session = await agent.openSession({
  signPayment: async ({ requirements, amountUsd }) => {
    // Your code: build the Solana SPL TransferChecked tx from the
    // requirements, sign it with the agent's wallet, base64-encode
    // the x402 PaymentPayload, return.
    return await signX402TransferChecked(keypair, requirements)
  },
})
// session.info: { id, capUsd, spentUsd, status, fundingTxHash, ... }

// 4. Call inference. The meter atomically debits session.spentUsd
//    against capUsd; cap exhausted -> 402 + session CLOSED.
const result = await session.chat({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'What is the capital of Japan?' }],
})

Why a signPayment callback?

x402 payments are Solana SPL TransferChecked transactions. Signing them needs the full Solana toolchain (@solana/web3.js, @solana/spl-token, an RPC connection). The SDK doesn't pull those in — instead you provide a small callback that does the signing with whatever wallet infrastructure you already have:

• A Phantom / Solflare wallet adapter
• @x402/svm-client from the x402 reference implementation
• A serverless KMS that holds the agent's private key
• An anchor Program signer if you're orchestrating from a Solana program

The keypair the SDK DOES use (passed to register) is only for one thing: signing the registration nonce. That's a single nacl.sign.detached(message, keypair.secretKey) call — pure tweetnacl, no Solana RPC needed — so the SDK handles it.

API

A2EAgent.register({ keypair, name?, apiBase? })

One-shot: request a challenge, sign with the keypair, submit. Returns an A2EAgent instance.

A2EAgent.fromApiKey({ apiKey, walletAddress, agentId, apiBase? })

Construct from a previously-saved api key. Use this in long-running processes to skip re-registration.

agent.openSession({ signPayment, preferredAmountAtomic? })

Opens an x402-funded session. The SDK handles the 402-challenge dance (probe → decode requirements → call your signPayment → retry with PAYMENT-SIGNATURE).

preferredAmountAtomic picks which tier to fund. Default tiers on TokenOS: 1000000 ($1), 5000000 ($5), 10000000 ($10), 25000000 ($25). Omit to use the smallest tier (accepts[0]).

session.chat(args) / session.embeddings(args)

OpenAI-compatible inference, billed to the session.

session.close() / session.refresh()

Self-close (forfeits unused cap) or re-fetch current state.

agent.revoke()

Revoke this agent's api key + cascade-close all open sessions. Permanent.

decodePaymentRequired(headerValue)

Exported utility: decode the base64-encoded payment-required header into the structured x402 PaymentRequirements. Useful if you want to show the user a tier picker before signing.

Errors

All thrown errors are A2EAgentError instances with .code and .status (HTTP status when applicable). Common codes:

• nonce_expired — challenge expired (>5 min between challenge and register)
• nonce_wallet_mismatch — signed challenge for wallet A, submitting as wallet B
• signature_signature_mismatch — signature didn't verify
• wallet_already_registered — 409, same wallet registered before
• agent_rate_limited — 429, per-agent RPM limit hit (default 100/min)
• session_over_cap / session_closed / session_not_found — meter-side rejections (402)

Spec

The full agent-auth specification lives at docs/AGENT_AUTH.md on the main repo. This SDK is a thin client over the protocol there — no platform-specific behavior baked in beyond URL paths.

License

MIT.