serve() Function

Start an HTTP server with x402 payment protection for your skills.

import { serve } from '@skillzmarket/sdk/creator';

Signature

function serve(
  skills: SkillsMap,
  options?: ServeOptions
): Promise<void>

Parameters

skills

A map of skill names to their definitions:

type SkillsMap = Record<string, SkillDefinition<any, any>>;

Each key becomes an endpoint: POST /[skillName]

const echo = skill({ price: '$0.001' }, async (input) => ({ echo: input }));
const upper = skill({ price: '$0.001' }, async ({ text }) => ({ result: text.toUpperCase() }));
 
// Creates endpoints: POST /echo, POST /upper
serve({ echo, upper });

options

interface ServeOptions {
  port?: number;
  wallet?: string;
  apiKey?: string;
  network?: `${string}:${string}`;
  facilitatorUrl?: string;
  appName?: string;
  onCall?: (skillName: string, input: unknown) => void;
  onError?: (skillName: string, error: Error) => void;
  register?: RegistrationOptions;
  trackCalls?: boolean;
  apiUrl?: string;
}

Property	Type	Default	Description
`port`	`number`	`3002`	Server port
`wallet`	`string`	`SKILLZ_WALLET_ADDRESS` env	Wallet address (42-char) or private key (66-char)
`apiKey`	`string`	`SKILLZ_API_KEY` env	API key for registration
`network`	`string`	`'eip155:8453'`	Payment network
`facilitatorUrl`	`string`	`'https://x402.dexter.cash'`	x402 facilitator
`appName`	`string`	`'Skillz Market Skill'`	App name for payments
`onCall`	`function`	-	Called on skill invocation
`onError`	`function`	-	Called on skill error
`register`	`RegistrationOptions`	-	Auto-registration config
`trackCalls`	`boolean`	`true`	Enable analytics
`apiUrl`	`string`	`'https://api.skillz.market'`	API URL for tracking

RegistrationOptions

interface RegistrationOptions {
  apiUrl?: string;
  endpoint: string;
  enabled?: boolean;
  onError?: 'throw' | 'warn' | 'silent';
}

Property	Type	Default	Description
`apiUrl`	`string`	`'https://api.skillz.market'`	Registry API URL
`endpoint`	`string`	Required	Your public server URL
`enabled`	`boolean`	`true`	Enable registration
`onError`	`string`	`'warn'`	Error handling mode

Returns

Promise<void> - Resolves when server is ready

Server Endpoints

GET /health

Health check endpoint (not protected).

{
  "status": "ok",
  "skills": ["echo", "upper"]
}

POST /[skillName]

Skill endpoints (x402 protected).

Without payment:

HTTP/1.1 402 Payment Required

With valid payment:

{
  "success": true,
  "result": { ... },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

On error:

{
  "success": false,
  "error": "Error message",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Examples

Basic Server

import { skill, serve } from '@skillzmarket/sdk/creator';
 
const echo = skill({ price: '$0.001' }, async (input) => ({ echo: input }));
 
serve({ echo });

With All Options

serve({ echo, translate, summarize }, {
  port: 8080,
  wallet: '0x4554A88d9e4D1bef5338F65A3Cd335C6A27E5368',
  apiKey: 'sk_...',
  network: 'eip155:8453',
  appName: 'My AI Skills',
  onCall: (name, input) => {
    console.log(`${name} called with:`, input);
  },
  onError: (name, error) => {
    console.error(`${name} failed:`, error.message);
  },
  register: {
    endpoint: 'https://api.example.com',
    enabled: true,
    onError: 'warn',
  },
  trackCalls: true,
});

Production Setup

import { serve, checkConfig } from '@skillzmarket/sdk/creator';
 
// Validate configuration
const config = checkConfig();
if (!config.configured) {
  console.error('Run: npx @skillzmarket/sdk init');
  process.exit(1);
}
 
serve(skills, {
  port: parseInt(process.env.PORT || '3002'),
  register: {
    endpoint: process.env.PUBLIC_URL!,
    enabled: process.env.NODE_ENV === 'production',
  },
  onError: (name, error) => {
    // Send to error tracking
    errorTracker.capture(error, { skill: name });
  },
});

Wallet Resolution

The wallet address is resolved in this order:

options.wallet parameter
SKILLZ_WALLET_ADDRESS environment variable
SKILLZ_WALLET_KEY environment variable (address is derived)

The wallet can be either:

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

# Using environment variable (recommended)
SKILLZ_WALLET_ADDRESS=0x... npx tsx index.ts

// Using parameter
serve({ echo }, {
  wallet: '0x4554A88d9e4D1bef5338F65A3Cd335C6A27E5368',
});

API Key Resolution

The API key is resolved in this order:

options.apiKey parameter
SKILLZ_API_KEY environment variable

Get an API key from skillz.market/dashboard.

Error Handling

Validation Errors

// Throws: No skills provided
serve({});
 
// Throws: Wallet not found
// (if neither wallet option nor env var is set)
serve({ echo });

Runtime Errors

Errors thrown by skill handlers are caught and returned as 500 responses:

const risky = skill({ price: '$0.01' }, async () => {
  throw new Error('Something went wrong');
});
 
// Returns: { success: false, error: "Something went wrong" }
// In production: { success: false, error: "Internal server error" }

serve() Function

On this page