Quickstart

End-to-end in five steps. By the end you’ll have a working agent that can sign and settle x402 payments on Fuji testnet.

1. Install the package

npm install @0xgasless/agent

Requires Node 18 or higher. Works in any JavaScript/TypeScript runtime with native fetch.

2. Get an API key

1. Open the 0xGasless Dashboard.
2. Create a project (or pick an existing one).
3. Go to Project → Auth → API Key and copy the key. It starts with 0xgas_live_sk_.

The API key is scoped to the project — every call you make is automatically scoped to it.

3. Initialise the client

import { OxGasAgent } from '@0xgasless/agent';

const client = new OxGasAgent({
  apiKey: process.env.OXGAS_API_KEY!,
});

That’s the whole config — apiUrl and facilitatorUrl default to production. See Configuration below for overrides.

4. Enable x402 + create your first agent

x402 is opt-in per project. Enable it once, then create an agent:

// One-time per project — idempotent
await client.policy.enableX402();

// Create an agent wallet (idempotent on agentId)
const agent = await client.agents.create({
  agentId:     'my-first-bot',
  displayName: 'Hello world bot',
  chain:       'fuji',          // 'avalanche' for mainnet, 'base' for Base
});

console.log('Agent address:', agent.address);
// → 0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b

The address is an EOA. Its private key is generated and held in 0xGasless KMS — your application never sees it.

5. Fund the wallet, then pay

Send a small amount of Fuji USDC to the agent’s address. Get free Fuji USDC + AVAX from the Avalanche Faucet (no AVAX needed in the agent wallet itself — the facilitator pays gas).

Once the agent has USDC, pay any address with x402.pay():

const result = await client.x402.pay({
  agentId: agent.agentId,
  to:      '0x000000000000000000000000000000000000dEaD',
  value:   '500000',   // atomic units: USDC has 6 decimals → 0.5 USDC
});

console.log('Transaction:', result.settle?.transaction);
console.log('Block:',       result.settle?.blockNumber);
console.log('Spent today:', result.signed.policy.spentTodayUSD, 'USD');

A successful call returns:

{
  "agentId": "my-first-bot",
  "signed": {
    "payerAddress": "0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b",
    "paymentPayload": { /* canonical x402 v2 payload */ },
    "paymentRequirements": { "network": "avalanche-testnet", "chainId": 43113 },
    "agentId": "my-first-bot",
    "tokenSymbol": "USDC",
    "chain": "fuji",
    "policy": {
      "perTxCapUSD":      5,
      "perDayCapUSD":     50,
      "spentTodayUSD":    "0.500000",
      "remainingTodayUSD": "49.500000"
    }
  },
  "settle": {
    "success":     true,
    "transaction": "0x5972437a3695b2641855416da6b7f936ceda300c7536189a5dc237e1cc21a8e7",
    "network":     "avalanche-fuji",
    "payer":       "0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b",
    "blockNumber": 56206516
  }
}

That’s it — your agent just paid 0xdEaD half a USDC on Fuji, and you can verify the on-chain transaction on Snowtrace Testnet.

What just happened

Your code                Platform                On-chain
─────────                ────────                ────────
                              │                      │
client.x402.pay()  ──────────►│                      │
                              │ (1) check policy     │
                              │ (2) sign EIP-3009    │
                              │     with KMS         │
                              │                      │
                              │     submit ──────────►│ TransferWithAuthorization
                              │                      │   on USDC contract
                              │                      │   (facilitator pays gas)
                              │ ◄──── tx hash ───────│
result {transaction…} ◄───────│                      │

Three things to note:

• Policy is enforced before signing. A request that exceeds your tier’s per-call or per-day cap returns a 403 and no signature is produced. No accidental over-spends.
• The settle step never reverts because of gas. The facilitator wallet is funded and pays for the on-chain submission.
• EIP-3009 is the canonical x402 settlement. USDC implements it natively, so no relayer contract or pre-approve is needed.

Configuration

The defaults work for the 0xGasless production platform. Override when you need to:

const client = new OxGasAgent({
  apiKey:         '0xgas_live_sk_...',                  // required
  apiUrl:         'https://api.0xgasless.com',          // optional — defaults to production
  facilitatorUrl: 'https://x402.0xgasless.com',         // optional — point at a self-hosted facilitator
  fetch:          myCustomFetch,                        // optional — Node 18+ has built-in fetch
});

Next steps

• Agents — client.agents.* reference (create, list, get, balance, revoke).
• Payments — sign vs pay, validity windows, nonces.
• Identity — give your agent a public on-chain identity.
• Errors — every error code, what it means, what to do.