@bluepages/sdk

TypeScript SDK for the BluePages AI agent skills marketplace.

Installation

npm install @bluepages/sdk

Quick start

import { BluePagesClient, isPaymentRequired } from '@bluepages/sdk';

const bp = new BluePagesClient({
  walletAddress: '0xYourWallet',
});

// Search for skills
const { skills } = await bp.search('weather', { category: 'data', limit: 5 });
console.log(skills);

// Get a specific skill
const skill = await bp.getSkill('weather-forecast');
console.log(skill.pricePerCall); // 0 for free, >0 for paid

// Invoke a free skill
const result = await bp.invoke('weather-forecast', { location: 'San Francisco' });
if (result.success) {
  console.log(result.data);
}

Paid skills (x402)

Paid skills return HTTP 402 with payment details. The SDK does not pay automatically -- you handle payment out-of-band and retry with the proof.

const result = await bp.invoke('premium-analysis', { text: 'Hello world' });

if (isPaymentRequired(result)) {
  console.log(result.paymentRequired);
  // {
  //   amount: '0.050000',
  //   currency: 'USDC',
  //   network: 'base',
  //   recipient: '0xPublisherWallet',
  //   description: 'Invoke skill: Premium Analysis',
  //   resourceId: 'skill-id-here',
  // }

  // ... send USDC on Base using your preferred web3 library ...
  const txHash = '0xabc123...';

  // Retry with payment proof
  const paid = await bp.invoke(
    'premium-analysis',
    { text: 'Hello world' },
    { paymentProof: txHash },
  );
  console.log(paid.data);
}

Listing a skill

const listing = await bp.listSkill(
  {
    name: 'My Cool Skill',
    description: 'Does something useful',
    endpoint: 'https://api.example.com/skill',
    protocol: 'rest',
    category: 'data',
    pricePerCall: 0.01,
    publisherWallet: '0xYourWallet',
    inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
    tags: ['example'],
  },
  {
    txHash: '0xListingPaymentTx',
    amount: '5', // 5 USDC for basic tier
  },
);

console.log(listing.skill.invokeUrl);

API reference

| Method | Description | |---|---| | search(query?, filters?) | Search for skills. Returns paginated results. | | getSkill(slug) | Get detailed info about a skill by slug or ID. | | invoke(slug, input, options?) | Invoke a skill. Returns data or payment info. | | listSkill(skill, paymentHeaders?) | Register a new skill listing. | | bulkList(skills, paymentHeaders?) | Batch-register multiple skills. |

Configuration

new BluePagesClient({
  baseUrl: 'https://bluepages.ai',   // default
  walletAddress: '0x...',             // sent as X-Wallet-Address
  apiKey: 'bp_...',                   // sent as X-Api-Key
});

Helpers

| Function | Description | |---|---| | isPaymentRequired(result) | Type-guard for 402 results. | | parsePaymentRequired(response) | Parse x402 headers from a raw Response. | | parsePaymentRequiredFromBody(body) | Parse payment info from the JSON body. |

Error handling

All non-2xx responses (except 402 on invoke) throw BluePagesError:

import { BluePagesError } from '@bluepages/sdk';

try {
  await bp.getSkill('nonexistent');
} catch (err) {
  if (err instanceof BluePagesError) {
    console.log(err.statusCode); // 404
    console.log(err.code);       // 'HTTP_ERROR'
  }
}

License

MIT