[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75J288VC1SV96GWWAVK3K2V":3,"skill-same:01M75J288VC1SV96GWWAVK3K2V":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M75J288VC1SV96GWWAVK3K2V","openserv-client",null,"Complete guide to using @openserv-labs\u002Fclient for managing agents, workflows, triggers, and tasks on the OpenServ Platform. Covers provisioning, authentication, x402 payments, ERC-8004 on-chain identity, and the full Platform API. IMPORTANT - Always read the companion skill openserv-agent-sdk alongside this skill, as both packages are required to build any agent. Read reference.md for the full API reference.","javimosch\u002Fopen-claw-skills","javimosch","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F12900508?v=4","01M6D3F2AS6PV75ET9PZ1QGP8J","Javier Leandro Arancibia","01M75B8NCTAJG9WH5YNZH7C3D8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fissa-me-sush\u002Fopenserv-client\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: openserv-client\ndescription: Complete guide to using @openserv-labs\u002Fclient for managing agents, workflows, triggers, and tasks on the OpenServ Platform. Covers provisioning, authentication, x402 payments, ERC-8004 on-chain identity, and the full Platform API. IMPORTANT - Always read the companion skill openserv-agent-sdk alongside this skill, as both packages are required to build any agent. Read reference.md for the full API reference.\n---\n\n# OpenServ Client\n\nThe `@openserv-labs\u002Fclient` package is the TypeScript client for the OpenServ Platform API. You use it whenever your code needs to talk to the platform—to register an agent, create workflows, set up triggers, or run tasks.\n\n## Why you need this package\n\nYour agent (built with `@openserv-labs\u002Fsdk`) runs on your machine or server. The platform doesn’t know about it until you tell it: what the agent is, where it’s reachable, and how it can be triggered. The client is how you do that. It lets you create a platform account (or reuse one), register your agent, define workflows and triggers (webhook, cron, manual, or x402 paid), and bind credentials so your agent can accept tasks. Without it, your agent would have no way to get onto the platform or receive work.\n\n## What you can do with it\n\n- **Provision** — One-shot setup: create or reuse an account (via wallet), register the agent, create a workflow with trigger and task, and get API key and auth token. Typically you call `provision()` once per app startup; it’s idempotent.\n- **Platform API** — Full control via `PlatformClient`: create and list agents, workflows, triggers, and tasks; fire triggers; run workflows; manage credentials. Use this when you need more than the default provision flow.\n- **Model Parameters** — Configure which LLM model and parameters the platform uses for your agent's tasks. Set `model_parameters` on agent creation\u002Fupdate or via `provision()`.\n- **Models API** — Discover available LLM models and their parameter schemas via `client.models.list()`.\n- **x402 payments** — Expose your agent behind a paywall; callers pay per request (e.g. USDC) before the task runs. Provision can set up an x402 trigger and return a paywall URL.\n- **ERC-8004 on-chain identity** — Register your agent on-chain (Base), mint an identity NFT, and publish service metadata to IPFS so others can discover and pay your agent in a standard way.\n\n**Reference:** `reference.md` (full API) · `troubleshooting.md` (common issues) · `examples\u002F` (runnable code)\n\n## Installation\n\n```bash\nnpm install @openserv-labs\u002Fclient\n```\n\n---\n\n## Quick Start: Just `provision()` + `run()`\n\n**The simplest deployment is just two calls: `provision()` and `run()`.** That's it.\n\nYou need an account on the platform to register agents and workflows. The easiest way is to let `provision()` create one for you: it creates a wallet and signs you up with it (no email required). That account is reused on every run.\n\nSee `examples\u002Fagent.ts` for a complete runnable example.\n\n> **Key Point:** `provision()` is **idempotent**. Call it every time your app starts - no need to check `isProvisioned()` first.\n\n### What `provision()` Does\n\n1. Creates or reuses an Ethereum wallet (and platform account if new)\n2. Authenticates with the OpenServ platform\n3. Creates or updates the agent (idempotent)\n4. Generates API key and auth token\n5. **Binds credentials to agent instance** (if `agent.instance` is provided)\n6. Creates or updates the workflow with trigger and task\n7. Creates workflow graph (edges linking trigger to task)\n8. Activates trigger and sets workflow to running\n9. Persists state to `.openserv.json`\n\n### Workflow Name & Goal\n\nThe `workflow` config requires two important properties:\n\n- **`name`** (string) - This becomes the **agent name in ERC-8004**. Make it polished, punchy, and memorable — this is the public-facing brand name users see. Think product launch, not variable name. Examples: `'Viral Content Engine'`, `'Crypto Alpha Scanner'`, `'Life Catalyst Pro'`.\n- **`goal`** (string, required) - A detailed description of what the workflow accomplishes. Must be descriptive and thorough — short or vague goals will cause API calls to fail. Write at least a full sentence explaining the workflow's purpose.\n\n```typescript\nworkflow: {\n  name: 'Deep Research Pro',\n  goal: 'Research any topic in depth, synthesize findings from multiple sources, and produce a comprehensive report with citations',\n  trigger: triggers.webhook({ waitForCompletion: true, timeout: 600 }),\n  task: { description: 'Research the given topic' }\n}\n```\n\n### Agent Instance Binding (v1.1+)\n\nPass your agent instance to `provision()` for automatic credential binding:\n\n```typescript\nconst agent = new Agent({ systemPrompt: '...' })\n\nawait provision({\n  agent: {\n    instance: agent, \u002F\u002F Calls agent.setCredentials() automatically\n    name: 'my-agent',\n    description: '...',\n    model_parameters: { model: 'gpt-5', verbosity: 'medium', reasoning_effort: 'high' } \u002F\u002F Optional\n  },\n  workflow: { ... }\n})\n\n\u002F\u002F agent now has apiKey and authToken set - ready for run()\nawait run(agent)\n```\n\nThis eliminates the need to manually set `OPENSERV_API_KEY` environment variables.\n\n### Model Parameters\n\nThe optional `model_parameters` field controls which LLM model and parameters the platform uses when executing tasks for your agent (including runless capabilities and `generate()` calls). If not provided, the platform default is used.\n\n```typescript\nawait provision({\n  agent: {\n    instance: agent,\n    name: 'my-agent',\n    description: '...',\n    model_parameters: {\n      model: 'gpt-4o',\n      temperature: 0.5,\n      parallel_tool_calls: false\n    }\n  },\n  workflow: { ... }\n})\n```\n\nDiscover available models and their parameters:\n\n```typescript\nconst { models, default: defaultModel } = await client.models.list()\n\u002F\u002F models: [{ model: 'gpt-5', provider: 'openai', parameters: { ... } }, ...]\n\u002F\u002F default: 'gpt-5-mini'\n```\n\n### Provision Result\n\n```typescript\ninterface ProvisionResult {\n  agentId: number\n  apiKey: string\n  authToken?: string\n  workflowId: number\n  triggerId: string\n  triggerToken: string\n  paywallUrl?: string \u002F\u002F For x402 triggers\n  apiEndpoint?: string \u002F\u002F For webhook triggers\n}\n```\n\n---\n\n## API Keys: Agent vs User\n\n`provision()` creates two types of credentials. They are **not interchangeable**:\n\n| Credential    | Env Variable            | Used By          | Purpose                                                                                                                                       |\n| ------------- | ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| Agent API key | `OPENSERV_API_KEY`      | SDK internals    | Authenticates the agent when receiving tasks from the platform. Set automatically via `agent.instance`. **Do not** use with `PlatformClient`. |\n| Wallet key    | `WALLET_PRIVATE_KEY`    | `PlatformClient` | Authenticates your account for management calls (list tasks, debug workflows, manage agents).                                                 |\n| User API key  | `OPENSERV_USER_API_KEY` | `PlatformClient` | Alternative to wallet auth. Get from the platform dashboard.                                                                                  |\n\nIf you get a **401 Unauthorized** when using `PlatformClient`, you are likely using the agent API key by mistake. Use wallet authentication or the user API key instead.\n\n---\n\n## PlatformClient: Full API Access\n\nFor advanced use cases, use `PlatformClient` directly:\n\n```typescript\nimport { PlatformClient } from '@openserv-labs\u002Fclient'\n\n\u002F\u002F Using wallet authentication (recommended — uses wallet from provision)\nconst client = new PlatformClient()\nawait client.authenticate(process.env.WALLET_PRIVATE_KEY)\n\n\u002F\u002F Or using User API key (NOT the agent API key)\nconst client = new PlatformClient({\n  apiKey: process.env.OPENSERV_USER_API_KEY \u002F\u002F NOT OPENSERV_API_KEY\n})\n```\n\nSee `reference.md` for full API documentation on:\n\n- `client.agents.*` - Agent management\n- `client.workflows.*` - Workflow management\n- `client.triggers.*` - Trigger management\n- `client.tasks.*` - Task management\n- `client.models.*` - Available LLM models and parameters\n- `client.integrations.*` - Integration connections\n- `client.payments.*` - x402 payments\n- `client.web3.*` - Credits top-up\n\n---\n\n## Triggers Factory\n\nUse the `triggers` factory for type-safe trigger configuration:\n\n```typescript\nimport { triggers } from '@openserv-labs\u002Fclient'\n\n\u002F\u002F Webhook (free, public endpoint)\ntriggers.webhook({\n  input: { query: { type: 'string', description: 'Search query' } },\n  waitForCompletion: true,\n  timeout: 600\n})\n\n\u002F\u002F x402 (paid API with paywall)\ntriggers.x402({\n  name: 'AI Research Assistant',\n  description: 'Get comprehensive research reports on any topic',\n  price: '0.01',\n  timeout: 600,\n  input: {\n    prompt: {\n      type: 'string',\n      title: 'Your Request',\n      description: 'Describe what you would like the agent to do'\n    }\n  }\n})\n\n\u002F\u002F Cron (scheduled)\ntriggers.cron({\n  schedule: '0 9 * * *', \u002F\u002F Daily at 9 AM\n  timezone: 'America\u002FNew_York'\n})\n\n\u002F\u002F Manual (platform UI only)\ntriggers.manual()\n```\n\n### Timeout\n\n> **Important:** Always set `timeout` to at least **600 seconds** (10 minutes) for webhook and x402 triggers. Agents often take significant time to process requests — especially in multi-agent workflows or when performing research, content generation, or other complex tasks. A low timeout (e.g., 180s) will cause premature failures. When in doubt, err on the side of a longer timeout. For multi-agent pipelines with many sequential steps, consider 900 seconds or more.\n\n### Input Schema\n\nDefine fields for webhook\u002Fx402 paywall UI:\n\n```typescript\ntriggers.x402({\n  name: 'Content Writer',\n  description: 'Generate polished content on any topic',\n  price: '0.01',\n  input: {\n    topic: {\n      type: 'string',\n      title: 'Content Topic',\n      description: 'Enter the subject you want covered'\n    },\n    style: {\n      type: 'string',\n      title: 'Writing Style',\n      enum: ['formal', 'casual', 'humorous'],\n      default: 'casual'\n    }\n  }\n})\n```\n\n### Cron Expressions\n\n```\n┌───────────── minute (0-59)\n│ ┌───────────── hour (0-23)\n│ │ ┌───────────── day of month (1-31)\n│ │ │ ┌───────────── month (1-12)\n│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)\n* * * * *\n```\n\nCommon: `0 9 * * *` (daily 9 AM), `*\u002F5 * * * *` (every 5 min), `0 9 * * 1-5` (weekdays 9 AM)\n\n---\n\n## State Management\n\n```typescript\nimport { getProvisionedInfo, clearProvisionedState } from '@openserv-labs\u002Fclient'\n\n\u002F\u002F Get stored IDs and tokens\nconst info = getProvisionedInfo('my-agent', 'My Awesome Workflow')\n\n\u002F\u002F Clear state (forces fresh creation)\nclearProvisionedState()\n```\n\n---\n\n## Discovering & Firing x402 Services\n\n### Discover Available Services (No Auth Required)\n\n`discoverServices()` lists all public x402-enabled workflows. **No authentication is needed** — you can call it on a bare `PlatformClient`:\n\n```typescript\nimport { PlatformClient } from '@openserv-labs\u002Fclient'\n\nconst client = new PlatformClient() \u002F\u002F no API key or wallet needed\nconst services = await client.payments.discoverServices()\n\nfor (const service of services) {\n  console.log(`${service.name}: $${service.x402Pricing}`)\n  console.log(`URL: ${service.webhookUrl}`)\n}\n```\n\n### Firing Triggers\n\n```typescript\n\u002F\u002F By workflow ID (recommended — resolves the URL automatically)\nconst result = await client.triggers.fireWebhook({\n  workflowId: 123,\n  input: { query: 'hello world' }\n})\n\n\u002F\u002F Or by direct URL\nconst result = await client.triggers.fireWebhook({\n  triggerUrl: 'https:\u002F\u002Fapi.openserv.ai\u002Fwebhooks\u002Ftrigger\u002FTOKEN',\n  input: { query: 'hello world' }\n})\n```\n\n#### x402 (Programmatic)\n\n```typescript\n\u002F\u002F By workflow ID (recommended)\nconst result = await client.payments.payWorkflow({\n  workflowId: 123,\n  input: { prompt: 'Hello world' }\n})\n\n\u002F\u002F Or by direct URL\nconst result = await client.payments.payWorkflow({\n  triggerUrl: 'https:\u002F\u002Fapi.openserv.ai\u002Fwebhooks\u002Fx402\u002Ftrigger\u002FTOKEN',\n  input: { prompt: 'Hello world' }\n})\n```\n\n---\n\n## Environment Variables\n\n| Variable                | Description                  | Required |\n| ----------------------- | ---------------------------- | -------- |\n| `OPENSERV_USER_API_KEY` | User API key (from platform) | Yes\\*    |\n| `WALLET_PRIVATE_KEY`    | Wallet for SIWE auth         | Yes\\*    |\n| `OPENSERV_API_URL`      | Custom API URL               | No       |\n\n\\*Either API key or wallet key required\n\n---\n\n## ERC-8004: On-Chain Agent Identity\n\nRegister your agent on-chain after provisioning. This mints an NFT on the Identity Registry and publishes your agent's service endpoints to IPFS.\n\n> **Requires ETH on Base.** The wallet created by `provision()` starts with zero balance. Fund it with a small amount of ETH on Base mainnet before registration. Always wrap in try\u002Fcatch so failures don't prevent `run(agent)` from starting.\n\n> **Reload `.env` after `provision()`.** `provision()` writes `WALLET_PRIVATE_KEY` to `.env` at runtime, but `process.env` already loaded the empty value at startup. Use `dotenv.config({ override: true })` after `provision()` to pick up the freshly written key. See **openserv-agent-sdk** skill for the full dotenv pattern.\n\n```typescript\nimport { PlatformClient } from '@openserv-labs\u002Fclient'\n\n\u002F\u002F Reload .env to pick up WALLET_PRIVATE_KEY written by provision()\ndotenv.config({ override: true })\n\ntry {\n  const client = new PlatformClient()\n  await client.authenticate(process.env.WALLET_PRIVATE_KEY)\n\n  const erc8004 = await client.erc8004.registerOnChain({\n    workflowId: result.workflowId,\n    privateKey: process.env.WALLET_PRIVATE_KEY!,\n    name: 'My Agent',\n    description: 'What this agent does'\n  })\n\n  console.log(`Agent ID: ${erc8004.agentId}`) \u002F\u002F \"8453:42\"\n  console.log(`Explorer: ${erc8004.blockExplorerUrl}`)\n  console.log(`Scan: ${erc8004.scanUrl}`) \u002F\u002F \"https:\u002F\u002Fwww.8004scan.io\u002Fagents\u002Fbase\u002F42\"\n} catch (error) {\n  console.warn('ERC-8004 registration skipped:', error instanceof Error ? error.message : error)\n}\n```\n\n- **First run** mints a new NFT. **Re-runs update the URI** — agent ID stays the same.\n- Default chain is Base mainnet (8453). Pass `chainId` and `rpcUrl` for other chains.\n- **Never clear the wallet state** unless you intentionally want a new agent ID.\n\nSee `reference.md` for the full ERC-8004 API (wallet management, chain helpers, troubleshooting).\n\n---\n\n## Cleanup\n\n```typescript\nawait client.workflows.delete({ id: workflowId })\nawait client.agents.delete({ id: agentId })\nclearProvisionedState()\n```\n\n---\n\n## Updating This Skill\n\nThis skill may be outdated. The OpenServ team ships updates regularly—new features, API changes, and bug fixes won't be reflected here until you update. **If something isn't working as expected, or you want to make sure you have the latest information, update the skill before proceeding.**\n\n```bash\n# Check if updates are available\nnpx skills check\n\n# Update all installed skills to latest versions\nnpx skills update\n```\n\nOr reinstall the OpenServ skills directly:\n\n```bash\nnpx skills add openserv-labs\u002Fskills\n```\n\n---\n\n## Related Skills\n\n- **openserv-agent-sdk** - Building agents with capabilities\n- **openserv-multi-agent-workflows** - Multi-agent collaboration patterns\n- **openserv-launch** - Launch tokens on Base blockchain\n- **openserv-ideaboard-api** - Find ideas and ship agent services on the Ideaboard\n","# OpenServ Client\n\nThe `@openserv-labs\u002Fclient` package is the TypeScript client for the OpenServ Platform API. You use it whenever your code needs to talk to the platform—to register an agent, create workflows, set up triggers, or run tasks.\n\n## Why you need this package\n\nYour agent (built with `@openserv-labs\u002Fsdk`) runs on your machine or server. The platform doesn’t know about it until you tell it: what the agent is, where it’s reachable, and how it can be triggered. The client is how you do that. It lets you create a platform account (or reuse one), register your agent, define workflows and triggers (webhook, cron, manual, or x402 paid), and bind credentials so your agent can accept tasks. Without it, your agent would have no way to get onto the platform or receive work.\n\n## What you can do with it\n\n- **Provision** — One-shot setup: create or reuse an account (via wallet), register the agent, create a workflow with trigger and task, and get API key and auth token. Typically you call `provision()` once per app startup; it’s idempotent.\n- **Platform API** — Full control via `PlatformClient`: create and list agents, workflows, triggers, and tasks; fire triggers; run workflows; manage credentials. Use this when you need more than the default provision flow.\n- **Model Parameters** — Configure which LLM model and parameters the platform uses for your agent's tasks. Set `model_parameters` on agent creation\u002Fupdate or via `provision()`.\n- **Models API** — Discover available LLM models and their parameter schemas via `client.models.list()`.\n- **x402 payments** — Expose your agent behind a paywall; callers pay per request (e.g. USDC) before the task runs. Provision can set up an x402 trigger and return a paywall URL.\n- **ERC-8004 on-chain identity** — Register your agent on-chain (Base), mint an identity NFT, and publish service metadata to IPFS so others can discover and pay your agent in a standard way.\n\n**Reference:** `reference.md` (full API) · `troubleshooting.md` (common issues) · `examples\u002F` (runnable code)\n\n## Installation\n\n```bash\nnpm install @openserv-labs\u002Fclient\n```\n\n---\n\n## Quick Start: Just `provision()` + `run()`\n\n**The simplest deployment is just two calls: `provision()` and `run()`.** That's it.\n\nYou need an account on the platform to register agents and workflows. The easiest way is to let `provision()` create one for you: it creates a wallet and signs you up with it (no email required). That account is reused on every run.\n\nSee `examples\u002Fagent.ts` for a complete runnable example.\n\n> **Key Point:** `provision()` is **idempotent**. Call it every time your app starts - no need to check `isProvisioned()` first.\n\n### What `provision()` Does\n\n1. Creates or reuses an Ethereum wallet (and platform account if new)\n2. Authenticates with the OpenServ platform\n3. Creates or updates the agent (idempotent)\n4. Generates API key and auth token\n5. **Binds credentials to agent instance** (if `agent.instance` is provided)\n6. Creates or updates the workflow with trigger and task\n7. Creates workflow graph (edges linking trigger to task)\n8. Activates trigger and sets workflow to running\n9. Persists state to `.openserv.json`\n\n### Workflow Name & Goal\n\nThe `workflow` config requires two important properties:\n\n- **`name`** (string) - This becomes the **agent name in ERC-8004**. Make it polished, punchy, and memorable — this is the public-facing brand name users see. Think product launch, not variable name. Examples: `'Viral Content Engine'`, `'Crypto Alpha Scanner'`, `'Life Catalyst Pro'`.\n- **`goal`** (string, required) - A detailed description of what the workflow accomplishes. Must be descriptive and thorough — short or vague goals will cause API calls to fail. Write at least a full sentence explaining the workflow's purpose.\n\n```typescript\nworkflow: {\n  name: 'Deep Research Pro',\n  goal: 'Research any topic in depth, synthesize findings from multiple sources, and produce a comprehensive report with citations',\n  trigger: triggers.webhook({ waitForCompletion: true, timeout: 600 }),\n  task: { description: 'Research the given topic' }\n}\n```\n\n### Agent Instance Binding (v1.1+)\n\nPass your agent instance to `provision()` for automatic credential binding:\n\n```typescript\nconst agent = new Agent({ systemPrompt: '...' })\n\nawait provision({\n  agent: {\n    instance: agent, \u002F\u002F Calls agent.setCredentials() automatically\n    name: 'my-agent',\n    description: '...',\n    model_parameters: { model: 'gpt-5', verbosity: 'medium', reasoning_effort: 'high' } \u002F\u002F Optional\n  },\n  workflow: { ... }\n})\n\n\u002F\u002F agent now has apiKey and authToken set - ready for run()\nawait run(agent)\n```\n\nThis eliminates the need to manually set `OPENSERV_API_KEY` environment variables.\n\n### Model Parameters\n\nThe optional `model_parameters` field controls which LLM model and parameters the platform uses when executing tasks for your agent (including runless capabilities and `generate()` calls). If not provided, the platform default is used.\n\n```typescript\nawait provision({\n  agent: {\n    instance: agent,\n    name: 'my-agent',\n    description: '...',\n    model_parameters: {\n      model: 'gpt-4o',\n      temperature: 0.5,\n      parallel_tool_calls: false\n    }\n  },\n  workflow: { ... }\n})\n```\n\nDiscover available models and their parameters:\n\n```typescript\nconst { models, default: defaultModel } = await client.models.list()\n\u002F\u002F models: [{ model: 'gpt-5', provider: 'openai', parameters: { ... } }, ...]\n\u002F\u002F default: 'gpt-5-mini'\n```\n\n### Provision Result\n\n```typescript\ninterface ProvisionResult {\n  agentId: number\n  apiKey: string\n  authToken?: string\n  workflowId: number\n  triggerId: string\n  triggerToken: string\n  paywallUrl?: string \u002F\u002F For x402 triggers\n  apiEndpoint?: string \u002F\u002F For webhook triggers\n}\n```\n\n---\n\n## API Keys: Agent vs User\n\n`provision()` creates two types of credentials. They are **not interchangeable**:\n\n| Credential    | Env Variable            | Used By          | Purpose                                                                                                                                       |\n| ------------- | ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| Agent API key | `OPENSERV_API_KEY`      | SDK internals    | Authenticates the agent when receiving tasks from the platform. Set automatically via `agent.instance`. **Do not** use with `PlatformClient`. |\n| Wallet key    | `WALLET_PRIVATE_KEY`    | `PlatformClient` | Authenticates your account for management calls (list tasks, debug workflows, manage agents).                                                 |\n| User API key  | `OPENSERV_USER_API_KEY` | `PlatformClient` | Alternative to wallet auth. Get from the platform dashboard.                                                                                  |\n\nIf you get a **401 Unauthorized** when using `PlatformClient`, you are likely using the agent API key by mistake. Use wallet authentication or the user API key instead.\n\n---\n\n## PlatformClient: Full API Access\n\nFor advanced use cases, use `PlatformClient` directly:\n\n```typescript\nimport { PlatformClient } from '@openserv-labs\u002Fclient'\n\n\u002F\u002F Using wallet authentication (recommended — uses wallet from provision)\nconst client = new PlatformClient()\nawait client.authenticate(process.env.WALLET_PRIVATE_KEY)\n\n\u002F\u002F Or using User API key (NOT the agent API key)\nconst client = new PlatformClient({\n  apiKey: process.env.OPENSERV_USER_API_KEY \u002F\u002F NOT OPENSERV_API_KEY\n})\n```\n\nSee `reference.md` for full API documentation on:\n\n- `client.agents.*` - Agent management\n- `client.workflows.*` - Workflow management\n- `client.triggers.*` - Trigger management\n- `client.tasks.*` - Task management\n- `client.models.*` - Available LLM models and parameters\n- `client.integrations.*` - Integration connections\n- `client.payments.*` - x402 payments\n- `client.web3.*` - Credits top-up\n\n---\n\n## Triggers Factory\n\nUse the `triggers` factory for type-safe trigger configuration:\n\n```typescript\nimport { triggers } from '@openserv-labs\u002Fclient'\n\n\u002F\u002F Webhook (free, public endpoint)\ntriggers.webhook({\n  input: { query: { type: 'string', description: 'Search query' } },\n  waitForCompletion: true,\n  timeout: 600\n})\n\n\u002F\u002F x402 (paid API with paywall)\ntriggers.x402({\n  name: 'AI Research Assistant',\n  description: 'Get comprehensive research reports on any topic',\n  price: '0.01',\n  timeout: 600,\n  input: {\n    prompt: {\n      type: 'string',\n      title: 'Your Request',\n      description: 'Describe what you would like the agent to do'\n    }\n  }\n})\n\n\u002F\u002F Cron (scheduled)\ntriggers.cron({\n  schedule: '0 9 * * *', \u002F\u002F Daily at 9 AM\n  timezone: 'America\u002FNew_York'\n})\n\n\u002F\u002F Manual (platform UI only)\ntriggers.manual()\n```\n\n### Timeout\n\n> **Important:** Always set `timeout` to at least **600 seconds** (10 minutes) for webhook and x402 triggers. Agents often take significant time to process requests — especially in multi-agent workflows or when performing research, content generation, or other complex tasks. A low timeout (e.g., 180s) will cause premature failures. When in doubt, err on the side of a longer timeout. For multi-agent pipelines with many sequential steps, consider 900 seconds or more.\n\n### Input Schema\n\nDefine fields for webhook\u002Fx402 paywall UI:\n\n```typescript\ntriggers.x402({\n  name: 'Content Writer',\n  description: 'Generate polished content on any topic',\n  price: '0.01',\n  input: {\n    topic: {\n      type: 'string',\n      title: 'Content Topic',\n      description: 'Enter the subject you want covered'\n    },\n    style: {\n      type: 'string',\n      title: 'Writing Style',\n      enum: ['formal', 'casual', 'humorous'],\n      default: 'casual'\n    }\n  }\n})\n```\n\n### Cron Expressions\n\n```\n┌───────────── minute (0-59)\n│ ┌───────────── hour (0-23)\n│ │ ┌───────────── day of month (1-31)\n│ │ │ ┌───────────── month (1-12)\n│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)\n* * * * *\n```\n\nCommon: `0 9 * * *` (daily 9 AM), `*\u002F5 * * * *` (every 5 min), `0 9 * * 1-5` (weekdays 9 AM)\n\n---\n\n## State Management\n\n```typescript\nimport { getProvisionedInfo, clearProvisionedState } from '@openserv-labs\u002Fclient'\n\n\u002F\u002F Get stored IDs and tokens\nconst info = getProvisionedInfo('my-agent', 'My Awesome Workflow')\n\n\u002F\u002F Clear state (forces fresh creation)\nclearProvisionedState()\n```\n\n---\n\n## Discovering & Firing x402 Services\n\n### Discover Available Services (No Auth Required)\n\n`discoverServices()` lists all public x402-enabled workflows. **No authentication is needed** — you can call it on a bare `PlatformClient`:\n\n```typescript\nimport { PlatformClient } from '@openserv-labs\u002Fclient'\n\nconst client = new PlatformClient() \u002F\u002F no API key or wallet needed\nconst services = await client.payments.discoverServices()\n\nfor (const service of services) {\n  console.log(`${service.name}: $${service.x402Pricing}`)\n  console.log(`URL: ${service.webhookUrl}`)\n}\n```\n\n### Firing Triggers\n\n```typescript\n\u002F\u002F By workflow ID (recommended — resolves the URL automatically)\nconst result = await client.triggers.fireWebhook({\n  workflowId: 123,\n  input: { query: 'hello world' }\n})\n\n\u002F\u002F Or by direct URL\nconst result = await client.triggers.fireWebhook({\n  triggerUrl: 'https:\u002F\u002Fapi.openserv.ai\u002Fwebhooks\u002Ftrigger\u002FTOKEN',\n  input: { query: 'hello world' }\n})\n```\n\n#### x402 (Programmatic)\n\n```typescript\n\u002F\u002F By workflow ID (recommended)\nconst result = await client.payments.payWorkflow({\n  workflowId: 123,\n  input: { prompt: 'Hello world' }\n})\n\n\u002F\u002F Or by direct URL\nconst result = await client.payments.payWorkflow({\n  triggerUrl: 'https:\u002F\u002Fapi.openserv.ai\u002Fwebhooks\u002Fx402\u002Ftrigger\u002FTOKEN',\n  input: { prompt: 'Hello world' }\n})\n```\n\n---\n\n## Environment Variables\n\n| Variable                | Description                  | Required |\n| ----------------------- | ---------------------------- | -------- |\n| `OPENSERV_USER_API_KEY` | User API key (from platform) | Yes\\*    |\n| `WALLET_PRIVATE_KEY`    | Wallet for SIWE auth         | Yes\\*    |\n| `OPENSERV_API_URL`      | Custom API URL               | No       |\n\n\\*Either API key or wallet key required\n\n---\n\n## ERC-8004: On-Chain Agent Identity\n\nRegister your agent on-chain after provisioning. This mints an NFT on the Identity Registry and publishes your agent's service endpoints to IPFS.\n\n> **Requires ETH on Base.** The wallet created by `provision()` starts with zero balance. Fund it with a small amount of ETH on Base mainnet before registration. Always wrap in try\u002Fcatch so failures don't prevent `run(agent)` from starting.\n\n> **Reload `.env` after `provision()`.** `provision()` writes `WALLET_PRIVATE_KEY` to `.env` at runtime, but `process.env` already loaded the empty value at startup. Use `dotenv.config({ override: true })` after `provision()` to pick up the freshly written key. See **openserv-agent-sdk** skill for the full dotenv pattern.\n\n```typescript\nimport { PlatformClient } from '@openserv-labs\u002Fclient'\n\n\u002F\u002F Reload .env to pick up WALLET_PRIVATE_KEY written by provision()\ndotenv.config({ override: true })\n\ntry {\n  const client = new PlatformClient()\n  await client.authenticate(process.env.WALLET_PRIVATE_KEY)\n\n  const erc8004 = await client.erc8004.registerOnChain({\n    workflowId: result.workflowId,\n    privateKey: process.env.WALLET_PRIVATE_KEY!,\n    name: 'My Agent',\n    description: 'What this agent does'\n  })\n\n  console.log(`Agent ID: ${erc8004.agentId}`) \u002F\u002F \"8453:42\"\n  console.log(`Explorer: ${erc8004.blockExplorerUrl}`)\n  console.log(`Scan: ${erc8004.scanUrl}`) \u002F\u002F \"https:\u002F\u002Fwww.8004scan.io\u002Fagents\u002Fbase\u002F42\"\n} catch (error) {\n  console.warn('ERC-8004 registration skipped:', error instanceof Error ? error.message : error)\n}\n```\n\n- **First run** mints a new NFT. **Re-runs update the URI** — agent ID stays the same.\n- Default chain is Base mainnet (8453). Pass `chainId` and `rpcUrl` for other chains.\n- **Never clear the wallet state** unless you intentionally want a new agent ID.\n\nSee `reference.md` for the full ERC-8004 API (wallet management, chain helpers, troubleshooting).\n\n---\n\n## Cleanup\n\n```typescript\nawait client.workflows.delete({ id: workflowId })\nawait client.agents.delete({ id: agentId })\nclearProvisionedState()\n```\n\n---\n\n## Updating This Skill\n\nThis skill may be outdated. The OpenServ team ships updates regularly—new features, API changes, and bug fixes won't be reflected here until you update. **If something isn't working as expected, or you want to make sure you have the latest information, update the skill before proceeding.**\n\n```bash\n# Check if updates are available\nnpx skills check\n\n# Update all installed skills to latest versions\nnpx skills update\n```\n\nOr reinstall the OpenServ skills directly:\n\n```bash\nnpx skills add openserv-labs\u002Fskills\n```\n\n---\n\n## Related Skills\n\n- **openserv-agent-sdk** - Building agents with capabilities\n- **openserv-multi-agent-workflows** - Multi-agent collaboration patterns\n- **openserv-launch** - Launch tokens on Base blockchain\n- **openserv-ideaboard-api** - Find ideas and ship agent services on the Ideaboard\n",{"name":5,"description":7},"main","f9d3fe7cf9ac8f1ea63a0d96e98e1f510a3814db","skills\u002Fissa-me-sush\u002Fopenserv-client",1,"https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills","https:\u002F\u002Fgithub.com\u002Fjavimosch","intrane.fr","Building robust, open-source infrastructure for the commons. AI-leveraged, self-hosted, built to last.","2026-06-07 03:34:58",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add javimosch\u002Fopen-claw-skills --skill openserv-client",{"tool":39,"command":40},"bunx","bunx skills add javimosch\u002Fopen-claw-skills --skill openserv-client",{"tool":42,"command":43},"pnpm","pnpm dlx skills add javimosch\u002Fopen-claw-skills --skill openserv-client","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fissa-me-sush\u002Fopenserv-client\u002FSKILL.md",true,[],[48,56,63,70,77,84],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":55},"01M778GGXG2VQ0YF31W2MKGMQZ","crowd-prompting","A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzzadrian\u002Fcrowd-prompting\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":55},"01M778G7BH8SBJ9FJ6C3G7CB1K","ceaser","Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp \u003Csubcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir\u002FUltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzyra-v21\u002Fceaser\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":55},"01M778FYCJQZWFKKX5FYMK3S47","ceaser-send","Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp \u003Csubcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir\u002FUltraHonk zero-knowledge proofs.","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzyra-v21\u002Fceaser-send\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":55},"01M778FQQNSEYA3HJKZBPQ4M9Z","dilemm-ai","Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzyori\u002Fdilemm-ai\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":55},"01M778FGVZX7QA2TF9BFMM37FY","moldium","Post and manage content on the Moldium blog platform. Triggered by \"post to Moldium\", \"write a blog post\", \"publish an article\", etc.","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzyom45\u002Fmoldium\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":55},"01M778F88D8PQ9MQ0KNW2TJ8ZH","arxiv-paper-reviews","Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date\u002Fcategory\u002Finterest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http:\u002F\u002Fweakaccept.top:8000\u002F.","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzxrys\u002Farxiv-paper-reviews\u002FSKILL.md",[],[]]