Serving Skills

The serve() function starts an HTTP server with x402 payment protection.

Basic Usage

import { skill, serve } from '@skillzmarket/sdk/creator';
 
const echo = skill({ price: '$0.001' }, async (input) => ({ echo: input }));
 
serve({ echo }, {
  register: {
    endpoint: 'https://your-server.com',
    enabled: true,
  },
});

Run your server:

npx tsx index.ts

Serve Options

interface ServeOptions {
  port?: number;               // Default: 3002
  wallet?: string;             // Address (42-char) or private key (66-char)
  apiKey?: string;             // API key for registration
  network?: string;            // Default: 'eip155:8453'
  facilitatorUrl?: string;     // Default: 'https://x402.dexter.cash'
  appName?: string;            // Default: 'Skillz Market Skill'
  register?: RegistrationOptions;
  onCall?: (name, input) => void;
  onError?: (name, error) => void;
  trackCalls?: boolean;        // Default: true
  apiUrl?: string;             // Default: 'https://api.skillz.market'
}

Port Configuration

serve({ echo }, {
  port: 8080,  // Listen on port 8080
});

Wallet Configuration

The wallet address is used for receiving payments. You can pass:

A 42-character address: 0x4554A88d9e4D1bef5338F65A3Cd335C6A27E5368
A 66-character private key (address is derived): 0x1234...

// Option 1: Environment variable (recommended)
// SKILLZ_WALLET_ADDRESS=0x... npx tsx index.ts
serve({ echo });
 
// Option 2: Pass directly
serve({ echo }, {
  wallet: '0x4554A88d9e4D1bef5338F65A3Cd335C6A27E5368',
});

Note: Private keys are no longer required for serving skills. The SDK only needs your wallet address to receive payments.

API Key Configuration

API keys authenticate registration requests:

// Option 1: Environment variable (recommended)
// SKILLZ_API_KEY=sk_... npx tsx index.ts
serve({ echo });
 
// Option 2: Pass directly
serve({ echo }, {
  apiKey: 'sk_...',
});

Get an API key from skillz.market/dashboard.

Network Configuration

Default is Base mainnet (eip155:8453):

serve({ echo }, {
  network: 'eip155:8453',  // Base mainnet
});

Callbacks

onCall

Called when a skill is invoked:

serve({ echo }, {
  onCall: (skillName, input) => {
    console.log(`Skill called: ${skillName}`);
    console.log('Input:', input);
  },
});

onError

Called when a skill throws an error:

serve({ echo }, {
  onError: (skillName, error) => {
    console.error(`Error in ${skillName}:`, error.message);
    // Send to error tracking service
  },
});

Server Endpoints

When you serve skills, these endpoints are available:

Endpoint	Method	Description
`/health`	GET	Health check (returns skill names)
`/[skillName]`	POST	Call a skill

Health Check

curl http://localhost:3002/health
# {"status":"ok","skills":["echo","uppercase"]}

Skill Endpoints

Each skill is available at POST /[skillName]:

curl -X POST http://localhost:3002/echo \
  -H "Content-Type: application/json" \
  -d '{"message": "hello"}'

Without payment, you'll get a 402 Payment Required response with x402 details.

Response Format

Skill responses follow this format:

// Success
{
  "success": true,
  "result": { /* your handler's return value */ },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
 
// Error
{
  "success": false,
  "error": "Error message",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Analytics Tracking

By default, skill calls are tracked for analytics:

serve({ echo }, {
  trackCalls: true,  // Default
  apiUrl: 'https://api.skillz.market',
});
 
// Disable tracking
serve({ echo }, {
  trackCalls: false,
});

Auto-Registration

Enable automatic registration with the marketplace:

serve({ echo }, {
  register: {
    endpoint: 'https://your-server.com',
    enabled: true,
    onError: 'warn',  // 'throw' | 'warn' | 'silent'
  },
});

See Registration for details.

Example: Production Setup

import { skill, serve, checkConfig } from '@skillzmarket/sdk/creator';
 
// Validate configuration
const config = checkConfig();
if (!config.configured) {
  console.error('Configuration issues:', config.issues);
  console.error('Run: npx @skillzmarket/sdk init');
  process.exit(1);
}
 
// Define skills
const summarize = skill({
  price: '$0.005',
  description: 'AI-powered text summarization',
  timeout: 30000,
}, async ({ text }) => {
  // Your AI logic
  return { summary: '...' };
});
 
const translate = skill({
  price: '$0.003',
  description: 'Multi-language translation',
}, async ({ text, target }) => {
  // Your translation logic
  return { translated: '...' };
});
 
// Serve with production settings
serve({ summarize, translate }, {
  port: process.env.PORT ? parseInt(process.env.PORT) : 3002,
  register: {
    endpoint: process.env.PUBLIC_URL || 'https://your-server.com',
    enabled: process.env.NODE_ENV === 'production',
    onError: 'warn',
  },
  onCall: (name, input) => {
    console.log(`[${new Date().toISOString()}] ${name} called`);
  },
  onError: (name, error) => {
    console.error(`[${new Date().toISOString()}] ${name} error:`, error);
  },
});

Environment Variables

Variable	Description
`SKILLZ_API_KEY`	API key for registration
`SKILLZ_WALLET_ADDRESS`	Wallet address for receiving payments
`SKILLZ_WALLET_KEY`	Private key (legacy, address is derived)

Next Steps

Registration - Register for marketplace discovery
x402 Payments - Understand the payment flow

Serving Skills

On this page