PaymentSkillX402 - x402 Protocol Support

npm install webagents
# or
pnpm add webagents

import { BaseAgent, http, pricing, Skill } from 'webagents';
import { PaymentX402Skill } from 'webagents/skills/payments';

class WeatherSkill extends Skill {
  readonly name = 'weather';

  @http({ path: '/weather', method: 'GET' })
  @pricing({ creditsPerCall: 0.05, reason: 'Weather API call' })
  async getWeather(params: { location: string }): Promise<unknown> {
    return { location: params.location, temperature: 72, conditions: 'sunny' };
  }
}

const agentB = new BaseAgent({
  name: 'weather-api',
  apiKey: process.env.ROBUTLER_API_KEY,
  skills: [
    new PaymentX402Skill({
      acceptedSchemes: [{ scheme: 'token', network: 'robutler' }],
    }),
    new WeatherSkill(),
  ],
});

import { BaseAgent } from 'webagents';
import { PaymentX402Skill } from 'webagents/skills/payments';

const agentA = new BaseAgent({
  name: 'consumer',
  apiKey: process.env.ROBUTLER_API_KEY,
  skills: [new PaymentX402Skill()],
});

// When the agent makes HTTP requests to paid endpoints:
// 1. Gets 402 response with payment requirements
// 2. Skill automatically creates payment
// 3. Retries with X-PAYMENT header
// 4. Returns result

new PaymentX402Skill({
  facilitatorUrl: 'https://robutler.ai/api/payments',
  acceptedSchemes: [{ scheme: 'token', network: 'robutler' }],
  maxPayment: 10.0,
});

new PaymentX402Skill({
  acceptedSchemes: [
    { scheme: 'token', network: 'robutler' },
    { scheme: 'exact', network: 'base-mainnet' },
  ],
});

// Coming soon — track at https://github.com/robutlerai/webagents/issues
// Direct blockchain wallet support (auto-exchange + signed payments) is
// currently Python-only. TypeScript handles the `token` scheme today.

import { http, pricing, Skill } from 'webagents';

class WeatherSkill extends Skill {
  readonly name = 'weather';

  @http({ path: '/weather', method: 'GET' })
  @pricing({ creditsPerCall: 0.05, reason: 'Weather API call', lock: true })
  async getWeather(params: { location: string }): Promise<unknown> {
    return { location: params.location, temperature: 72 };
  }

  @http({ path: '/analyze', method: 'POST' })
  @pricing({ creditsPerCall: 0.5, reason: 'Analysis', lock: true })
  async analyze(params: { data: unknown }): Promise<unknown> {
    return { ok: true };
  }
}

import { http, pricing, Skill } from 'webagents';

class AnalyzeSkill extends Skill {
  readonly name = 'analyze';

  @http({ path: '/analyze', method: 'POST' })
  @pricing()
  async analyzeData(params: {
    data: unknown;
    complexity?: 'basic' | 'advanced' | 'enterprise';
  }): Promise<unknown> {
    const tier = params.complexity ?? 'basic';
    const credits = { basic: 0.1, advanced: 0.5, enterprise: 2.0 }[tier];
    return {
      result: 'analysis result',
      _pricing: {
        credits,
        reason: `Data analysis (${tier})`,
        metadata: { complexity: tier },
      },
    };
  }
}

import type { PaymentX402Config } from 'webagents/skills/payments';

export class PaymentX402Skill extends Skill {
  constructor(config?: PaymentX402Config);
}

interface PaymentX402Config {
  facilitatorUrl?: string;
  acceptedSchemes?: Array<{ scheme: string; network: string }>;
  maxPayment?: number;
  // ... see PaymentSkillConfig for inherited options
}

import { hook } from 'webagents';

@hook({ lifecycle: 'before_http_call', priority: 10 })
async checkHttpEndpointPayment(data, context) {
  // Agent B:
  // - Checks if endpoint has @pricing decorator
  // - If no X-PAYMENT header: throws PaymentRequiredError
  // - If X-PAYMENT present: verifies and settles via facilitator
}

async def _get_available_token(self, context) -> Optional[str]: ...
async def _create_payment(
    self, accepts: List[Dict], context
) -> tuple[str, str, float]: ...
async def _exchange_for_credits(self, amount: float, context) -> str: ...

import { PaymentRequiredError } from 'webagents/skills/payments';

// PaymentRequiredError is the TS equivalent of PaymentRequired402.
// It carries the x402 `accepts` payload on `error.requirements`.
// Other errors are reported as standard `Error` instances with
// descriptive messages — fine-grained subclasses are coming soon.

import { BaseAgent, http, pricing, Skill } from 'webagents';
import { PaymentX402Skill } from 'webagents/skills/payments';

class TranslatorSkill extends Skill {
  readonly name = 'translator-skill';

  @http({ path: '/translate', method: 'POST' })
  @pricing({ creditsPerCall: 0.1, reason: 'Translation service' })
  async translate(params: { text: string; target_lang: string }): Promise<unknown> {
    return { translated: `[${params.target_lang}] ${params.text}` };
  }
}

const agent = new BaseAgent({
  name: 'translator',
  skills: [new PaymentX402Skill(), new TranslatorSkill()],
});

import { http, pricing, Skill } from 'webagents';

class ComputeSkill extends Skill {
  readonly name = 'compute';

  @http({ path: '/compute', method: 'POST' })
  @pricing()
  async compute(params: { task: unknown; tier?: 'basic' | 'standard' | 'premium' }): Promise<unknown> {
    const tier = params.tier ?? 'basic';
    const credits = { basic: 0.05, standard: 0.2, premium: 1.0 }[tier];
    return {
      result: 'computed',
      _pricing: { credits, reason: `Computation (${tier})`, metadata: { tier } },
    };
  }
}

// Coming soon — track at https://github.com/robutlerai/webagents/issues
// Auto-exchange and blockchain wallet payments are Python-only.
import { PaymentX402Skill } from 'webagents/skills/payments';

const consumer = new BaseAgent({
  name: 'api-consumer',
  skills: [new PaymentX402Skill({ maxPayment: 5.0 })],
});

import { PaymentRequiredError } from 'webagents/skills/payments';

try {
  const result = await agent.callEndpoint('/paid-api');
} catch (err) {
  if (err instanceof PaymentRequiredError) {
    console.log('Payment required:', (err as PaymentRequiredError).requirements);
  } else {
    console.error('Payment error:', (err as Error).message);
  }
}

import { BaseAgent } from 'webagents';
import { PaymentX402Skill } from 'webagents/skills/payments';
import { PortalTransportSkill } from 'webagents/skills/transport';

// Portal transport handles payment.required/submit/accepted over WS.
const agent = new BaseAgent({
  name: 'paid-agent',
  skills: [
    new PortalTransportSkill(),
    new PaymentX402Skill(),
  ],
});