@xgents/core

v0.3.2

Published

2 days ago

Decentralized infrastructure for autonomous AI agents on X Layer

0High
0Medium
0Low

martinvibes

xlayer x-layer okx ai agent agentic x402 infrastructure phone email wallet crypto

@xgents/core

The agent-native CLI and SDK for XGENT — real email inboxes, on-chain identity, and pay-per-call AI inference for autonomous agents on X Layer.

npm i -g @xgents/core
xgent setup                       # X Layer (USDC) by default
xgent compute infer "What can you do for my agent?"

Overview

@xgents/core is the official client for the XGENT API at api.xgent.xyz. One package ships two interfaces:

xgent CLI — for terminals and agent pipelines.
ZeroGent SDK — typed TypeScript class importable as @xgents/core.

Identity model. There are no user accounts. The wallet that signs each x402 payment becomes the owner of the resource it just paid for (an inbox, an NFT, a memory entry). Re-paying from the same wallet proves continued ownership. No API keys, no sessions.

Payments. USDC on X Layer (chain ID 196) — OKX's zkEVM. Gas is paid in OKB. X Layer is the default; the same CLI also supports Celo (USDC) and 0G Chain (native 0G). Select your chain once at setup and never think about it again.

Custody. Non-custodial. The seed phrase never leaves your machine. The XGENT server only ever sees public addresses and verifies payments by reading on-chain events.

Multi-chain. Pick your chain at xgent setup. X Layer (pay with USDC — the default), Celo (USDC), or 0G Chain (native 0G). Same wallet, same commands, same services across every chain.

Install

npm i -g @xgents/core

Or run any command without a global install — perfect for one-off agent scripts or CI:

npx @xgents/core compute providers
npx @xgents/core phone search --country US --area-code 415
npx @xgents/core compute infer "Summarise this in 10 words: ..."

Requires Node.js ≥ 18.

Quick start

The fastest path from zero to a working agent identity with a real inbox, on X Layer + USDC:

# 1. Generate an encrypted local wallet (BIP-39, AES-256-GCM)
#    — X Layer is selected by default when prompted for chain
xgent setup

# 2. Fund the wallet: bridge OKB (gas) + USDC to X Layer
#    — prints a QR + the OKX bridge link (okx.com/xlayer/bridge)
xgent wallet fund

# 3. Mint your agent identity NFT — ERC-8004 on X Layer ($0.10 USDC)
xgent identity mint

# 4. Claim a real <name>@xgent.xyz inbox ($0.20 USDC)
xgent email create --name scout

# 5. Send an actual email ($0.08 USDC)
xgent email send <inbox-id> --to [email protected] --subject "Hi" --body "from the agent"

# 6. Ask an LLM, paid in USDC ($0.10 USDC)
xgent compute infer "What is X Layer in one sentence?"

# 7. Search real phone-number inventory (free)
xgent phone search --country US --area-code 415

Every paid step is a real on-chain transaction on X Layer. Every resource is owned by your wallet, recorded on-chain, permanently.

Prefer Celo or 0G? Run xgent setup and pick your chain. On Celo, fund with USDC. On 0G Chain, fund with native 0G (free testnet tokens at faucet.0g.ai). All commands are identical; prices are quoted in that chain's token.

Status legend

✅ Live — wired end-to-end and verified in production at api.xgent.xyz.
🟡 In dev — code is shipped but the upstream provider isn't credentialed yet; calls return 5xx until it is.

Command reference

Prices below are shown in USDC (X Layer default). All costs are settled at request time via the x402 protocol — one payment per call, no subscriptions.

Setup & wallet

✅ All wallet operations run locally. The seed phrase never touches the server.

| Command | Cost | Notes | |---|---|---| | xgent setup | free | One-time interactive setup. Generates a BIP-39 wallet, encrypts it at ~/.xgent/, and prompts for chain (X Layer is default). | | xgent wallet create [--name N] | free | Generate an additional BIP-39 wallet locally. | | xgent wallet list | free | List all locally stored wallets. | | xgent wallet show | free | Show the active wallet's address + gas balance. | | xgent wallet use <idOrLabel> | free | Switch the default payer. | | xgent wallet fund | free | Print the funding QR code and the OKX bridge link (or the appropriate faucet/bridge for the active chain). | | xgent wallet export [idOrLabel] | free | Reveal the mnemonic. Prints only — never transmits. | | xgent balance | free | On-chain balance read for the active wallet (USDC on X Layer / Celo; 0G on 0G Chain). |

Identity

| Command | Cost | Status | Notes | |---|---|---|---| | xgent identity mint [--name N] | $0.10 USDC | ✅ | Mints an ERC-8004 agent identity NFT on X Layer. One per wallet. | | xgent identity show | free | ✅ | Show your minted token (id, metadataURI, resource count). |

Email

End-to-end: outbound via Resend, inbound parsed by an email worker (full MIME) and pushed to the backend webhook. All inboxes are <name>@xgent.xyz.

| Command | Cost | Status | Notes | |---|---|---|---| | xgent email create --name N | $0.20 USDC | ✅ | Provisions <N>@xgent.xyz and registers it on-chain. | | xgent email send <id> --to A --subject S --body B | $0.08 USDC | ✅ | Sends a real email via Resend. | | xgent email read <id> [--limit N] [--compact] | $0.02 USDC | ✅ | Card view by default; --compact for a dense table. | | xgent email threads <id> | $0.02 USDC | ✅ | List conversation threads for the inbox. |

Compute (AI inference)

Pay-per-call LLM inference. The XGENT operator fronts the upstream provider; agents reimburse the operator per call via x402. Agents do not need to maintain their own provider account or ledger.

On 0G Chain, inference can be routed through the decentralized 0G Compute Network (xgent compute providers lists live providers). On X Layer and Celo, the operator serves inference directly — same command, same response shape.

| Command | Cost | Status | Notes | |---|---|---|---| | xgent compute providers | free | ✅ | Live provider discovery (0G Compute — 0G chain only). No wallet required. | | xgent compute status | free | ✅ | Operator ledger balance + ready flag. ready: true means inference will succeed. | | xgent compute infer "<prompt>" [--model M] [--max-tokens N] [--system "..."] | $0.10 USDC | ✅ | Pay-per-call LLM. Returns { response, model, provider, usage } in OpenAI shape. |

Sample output on X Layer:

$ xgent compute infer "Reply with one short sentence: what is X Layer?"
Paying $0.10 USDC...
Approving USDC spend...
Waiting for confirmation (0xa3f1...)
✓ Inference complete

  ┌─ response ─────────────────────────────────────────
  │ X Layer is OKX's Ethereum-compatible zkEVM Layer 2,
  │ secured by Polygon CDK and settled on Ethereum.
  └────────────────────────────────────────────────────

  Model:    gpt-4o-mini
  Tokens:   41 (25 in / 16 out)

Memory

Agent memory is a key/value store indexed by your wallet address. Reads and writes are free at the API level (storage costs are absorbed by the operator). On 0G Chain, memory is backed by 0G Storage.

| Command | Cost | Status | Notes | |---|---|---|---| | xgent memory set <key> <value> | free | ✅ | Persist arbitrary JSON, indexed by your wallet. | | xgent memory get <key> | free | ✅ | Read a value by key. | | xgent memory list | free | ✅ | List keys. | | xgent memory delete <key> | free | ✅ | Remove an entry. |

Phone & SMS ✅

Live end-to-end on Twilio (verified account, worldwide coverage, messaging profile attached). Numbers are owned by your wallet and leased for 30 days.

| Command | Cost | Status | Notes | |---|---|---|---| | xgent phone countries [--region <name>] | free | ✅ | List the 50 curated supported countries; full upstream inventory is 170+. | | xgent phone search [--country US] [--area-code 415] | free | ✅ | Real upstream inventory. Country aliases (UK→GB, USA→US, full names) resolve automatically. | | xgent phone provision [<phoneNumber>] [--country US] | $0.50 USDC | ✅ | Pass an E.164 number to purchase that exact number, or --country to grab the first available. CLI pre-validates E.164 format before any payment. | | xgent phone sms <phoneId> --to +1... --body "..." | $0.01 USDC | ✅ | End-to-end SMS delivery verified. Pre-flight catches To==From, missing fields, and invalid E.164 before x402 charges. | | xgent phone logs <phoneId> | free | ✅ | Reads local DB; provider-agnostic. |

Utility

| Command | Cost | Notes | |---|---|---| | xgent list | free | All on-chain resources owned by your wallet. | | xgent skill | free | Print the live skill.md from the API — the LLM-readable capability manifest. | | xgent pricing | free | Live price table from /pricing. | | xgent health | free | API + chain status. | | xgent doctor | free | Diagnose your setup (config, wallet, RPC, contracts). Non-zero exit if anything fails. |

SDK

Install as a library dependency (not global):

npm i @xgents/core

import { ZeroGent } from '@xgents/core';

// Generate a fresh wallet locally — no network call.
const wallet = ZeroGent.createWallet('my-agent');
// → { name, address, mnemonic, privateKey, createdAt }

// Construct a client. It auto-pays x402 challenges using your private key.
// chain defaults to X Layer (196); pass chain: 42220 (Celo) or 16661 (0G) to switch.
const z = new ZeroGent({
  privateKey: wallet.privateKey,
  api: 'https://api.xgent.xyz',                          // optional
  onPaymentStatus: (msg) => console.log('[pay]', msg),   // optional progress hook
});

// ── Free reads ───────────────────────────────────────
await z.health();
await z.balance();
await z.pricing();

// ── Identity (paid) ──────────────────────────────────
const id = await z.identityMint('support-bot');    // $0.10 USDC on X Layer

// ── Email (paid) ─────────────────────────────────────
const inbox = await z.emailCreate('support');      // $0.20 USDC on X Layer
await z.emailSend(
  inbox.id,
  '[email protected]',
  'Receipt',
  'Thanks for your order.'                         // $0.08 USDC on X Layer
);
const messages = await z.emailRead(inbox.id);      // $0.02 USDC on X Layer

// ── Compute (free reads + paid inference) ────────────
const providers = await z.computeProviders();      // free
const status    = await z.computeStatus();         // free
const reply     = await z.computeInfer(            // $0.10 USDC on X Layer
  'What is X Layer in one sentence?',
  { maxTokens: 80 }
);
// reply: { response, model, provider, usage }

// ── Memory (free) ────────────────────────────────────
await z.memory.set('last_conv', { user: 'alice', topic: 'pricing' });
const m = await z.memory.get('last_conv');

// ── On-chain reads (free) ────────────────────────────
const resources = await z.listResources();

How a paid call works

The following diagram shows what happens when an agent calls z.computeInfer(...). Every other paid endpoint follows the same flow.

1. Agent       z.computeInfer('what is X Layer?')
                    │
2. Server      ▶ 402 Payment Required
                    "pay $0.10 USDC to Payment.pay(nonce, 'compute-infer', amount)"
                    │
3. SDK         ▶ approves USDC spend (ERC-20 approve), then calls the payment
                    contract on X Layer, waits for on-chain confirmation
                    │
4. Server      ▶ reads PaymentReceived event for that nonce → verified
                    │
5. Server      ▶ signs the upstream request and forwards it to the model provider
                    │
6. Provider    ▶ model returns an OpenAI-format completion
                    │
7. Agent       ◀ { response, model, provider, usage }

The payment contract address for the active chain is delivered inside each x402 challenge, so the SDK always pays the right contract. On X Layer, USDC is 0x74b7F16337b8972027F6196A17a631aC6dE26d22 (6 decimals) and the ERC-8004 identity contract is 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432.

Security model

| Question | Answer | |---|---| | Where are my keys stored? | Locally at ~/.xgent/, encrypted with AES-256-GCM, key derived via PBKDF2 (200 000 iterations) from your passphrase. | | Can the XGENT server spend my funds? | No. It only sees your public address. Every payment is signed locally by the SDK before broadcast. | | Can I run my own backend? | Yes. Pass api: 'https://your-host' to ZeroGent or set XGENT_API. | | Replay protection? | On-chain. Each x402 payment includes a unique nonce, enforced in the payment contract. The same nonce cannot be reused. | | What if I lose my mnemonic? | Same as any self-custody wallet — funds are unrecoverable. Save the mnemonic when xgent setup shows it. | | What data does the server store? | Resource metadata (inbox address, NFT token ID, etc.) in SQLite. No message content is stored server-side beyond forwarding. |

Environment variables

Both XGENT_* (preferred) and the legacy OGENT_* names are honored.

| Variable | Purpose | Default | |---|---|---| | XGENT_API | Override the API endpoint | https://api.xgent.xyz | | XGENT_CONFIG_DIR | Override wallet and config location | ~/.xgent | | XGENT_WALLET_PASSPHRASE | Skip the passphrase prompt (CI / agent runtimes) | — |

Troubleshooting

xgent doctor

doctor walks every subsystem (config, wallet, RPC, contracts) and prints a pass/fail line per check. Exits non-zero if anything is broken — safe to gate CI on.

Common issues:

No wallet configured — Run xgent setup first. (xgent compute providers and xgent compute status are exceptions — they work without a wallet.)
Insufficient balance on a paid call — On X Layer, fund your wallet with USDC and keep a little OKB for gas (bridge both at okx.com/xlayer/bridge). On Celo, fund with USDC. On 0G Chain, fund with 0G; free testnet tokens at faucet.0g.ai.
Slow Waiting for confirmation — X Layer blocks are fast (~sub-second to a few seconds). Longer delays usually indicate RPC pressure. The SDK auto-retries.
USDC approve failed — Make sure you're on the intended chain (xgent doctor validates the RPC chain ID against your config).

FAQ

Why X Layer? X Layer is OKX's Ethereum-compatible zkEVM, with USDC for stable pricing and OKB for gas. It's the default chain for XGENT — run xgent setup, press Enter, fund with USDC, and every command works. Prices are in USDC.

Is this real or a simulation? Real. Real on-chain payments. Real emails delivered. Real LLM completions returned. Running on X Layer mainnet (and Celo / 0G mainnet).

What if I lose my mnemonic? Same as MetaMask, same as any self-custody wallet. Save it when xgent setup shows it. There is no reset or recovery mechanism.

Can I use Celo or 0G instead? Yes. Both are fully supported — xgent setup lets you pick. Celo pays in USDC; 0G pays in native 0G (free testnet 0G at faucet.0g.ai).

My agent is a Python script — can I use this? The CLI is Node-based, but every paid action is just HTTP + an EVM signature. The skill catalog at https://api.xgent.xyz/skill.md documents the full raw HTTP API. Any language with an EVM-compatible signing library (ethers, web3.py, viem, etc.) works.

How does the server verify my payment? By reading PaymentReceived events from the payment contract on-chain, matching the nonce you signed in the x402 challenge. No cookies, no API keys, no sessions — the chain is the source of truth.

Can I have multiple wallets / agents? Yes. Use xgent wallet create to generate additional wallets and xgent wallet use to switch between them. Each wallet has its own set of owned resources.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xgents/core

Table of contents

Overview

Install

Quick start

Status legend

Command reference

Setup & wallet

Identity

Email

Compute (AI inference)

Memory

Phone & SMS ✅

Utility

SDK

How a paid call works

Security model

Environment variables

Troubleshooting

FAQ

Links

License