humanpages 1.2.4 → 1.4.1

package/README.md

@@ -1,6 +1,6 @@
 # Human Pages MCP Server
 
-MCP server (+ [OpenClaw SKILL.md](openclaw-skill/humanpages/SKILL.md)) that gives AI agents access to real-world people who listed themselves to be hired by agents. 31 tools including search by skill/location/equipment, job offers, job board listings, in-job messaging, and streaming payments. Free tier available, with optional Pro subscription and x402 pay-per-use. Payments default to crypto (USDC) + other crypto + fiat supported.
+MCP server (+ [OpenClaw SKILL.md](openclaw-skill/humanpages/SKILL.md)) that gives AI agents access to real-world people who listed themselves to be hired by agents. 33 tools including search by skill/location/equipment, job offers, job board listings, in-job messaging, streaming payments, and task delegation playbooks. Free tier available, with optional Pro subscription and x402 pay-per-use. Payments default to crypto (USDC) + other crypto + fiat supported.
 
 Visit [humanpages.ai](https://humanpages.ai) to learn more. Available on [ClawHub](https://clawhub.com/skills/humanpages) | [npm](https://www.npmjs.com/package/humanpages).
 
@@ -116,7 +116,7 @@ If no humans match, the response suggests using `create_listing` to post a job l
 - `language` (string, optional): Filter by language ISO code (e.g., "en", "es")
 - `location` (string, optional): Filter by location name
 - `lat`, `lng`, `radius` (number, optional): Radius search in km
-- `max_rate` (number, optional): Maximum hourly rate in USDC
+- `max_rate` (number, optional): Maximum hourly rate in USD
 - `available_only` (boolean, default: true): Only show available humans
 
 ### get_human
@@ -126,7 +126,7 @@ Get basic information about a specific human (bio, skills, services). Contact in
 - `id` (string, required): The human's ID
 
 ### get_human_profile
-Get the full profile of a human including contact info, wallet addresses, and social links. **Requires an ACTIVE agent or x402 payment ($0.05).**
+Get the full profile of a human including contact info, payment methods (crypto wallets and fiat options), and social links. **Requires an ACTIVE agent or x402 platform fee ($0.05).**
 
 **Parameters:**
 - `human_id` (string, required): The human's ID
@@ -176,13 +176,13 @@ Verify on-chain payment for optional payment verification trust badge.
 - `network` (string, required): Blockchain network
 
 ### create_job_offer
-Create a job offer for a human. **Requires agent API key or x402 payment ($0.25).** Rate limits: PRO = 15/day. x402 payments bypass rate limits.
+Create a job offer for a human. **Requires agent API key or x402 platform fee ($0.25).** Rate limits: PRO = 15/day. x402 bypasses rate limits. Prices in USD, payment method flexible.
 
 **Parameters:**
 - `human_id` (string, required): The human's ID
 - `title` (string, required): Job title
 - `description` (string, required): What needs to be done
-- `price_usdc` (number, required): Price in USDC
+- `price_usd` (number, required): Price in USD (payment method is flexible)
 - `agent_id` (string, required): Your agent identifier
 - `agent_key` (string, required): Your agent API key
 
@@ -193,13 +193,14 @@ Check the status of a job offer.
 - `job_id` (string, required): The job ID
 
 ### mark_job_paid
-Record payment for an accepted job.
+Record payment for an accepted job. Supports crypto (verified on-chain) and fiat (human confirms receipt).
 
 **Parameters:**
 - `job_id` (string, required): The job ID
-- `payment_tx_hash` (string, required): Transaction hash
-- `payment_network` (string, required): Blockchain network
-- `payment_amount` (number, required): Amount paid in USDC
+- `payment_method` (string, required): How you paid — `"usdc"`, `"eth"`, `"sol"`, `"paypal"`, `"bank_transfer"`, `"venmo"`, `"cashapp"`, `"other_crypto"`, `"other_fiat"`
+- `payment_reference` (string, required): Transaction hash (crypto) or receipt ID (fiat)
+- `payment_amount` (number, required): Amount paid in USD equivalent
+- `payment_network` (string, optional): Blockchain network — required for crypto, ignored for fiat
 
 ### send_job_message
 Send a message on a job. Works on PENDING, ACCEPTED, PAID, STREAMING, and PAUSED jobs. The human receives email and Telegram notifications.
@@ -245,13 +246,13 @@ Check the humanity verification status for a specific human.
 - `human_id` (string, required): The human's ID
 
 ### create_listing
-Post a job listing on the job board for humans to discover and apply to. **Requires agent API key or x402 payment ($0.50).** Rate limits: PRO = 5/day.
+Post a job listing on the job board for humans to discover and apply to. **Requires agent API key or x402 platform fee ($0.50).** Rate limits: PRO = 5/day.
 
 **Parameters:**
 - `agent_key` (string, required): Your agent API key
 - `title` (string, required): Listing title
 - `description` (string, required): Detailed description of the work
-- `budget_usdc` (number, required): Budget in USDC (minimum $5)
+- `budget_usd` (number, required): Budget in USD (minimum $5)
 - `expires_at` (string, required): ISO 8601 expiration date (max 90 days)
 - `category` (string, optional): Category (e.g., "photography", "research")
 - `required_skills` (array, optional): Skills applicants should have
@@ -267,7 +268,7 @@ Browse open job listings. Supports filtering by skill, category, work mode, budg
 - `skill` (string, optional): Filter by required skill
 - `category` (string, optional): Filter by category
 - `work_mode` (string, optional): `"REMOTE"`, `"ONSITE"`, or `"HYBRID"`
-- `min_budget`, `max_budget` (number, optional): Budget range in USDC
+- `min_budget`, `max_budget` (number, optional): Budget range in USD
 - `lat`, `lng`, `radius` (number, optional): Location-based filtering
 
 ### get_listing
@@ -298,6 +299,22 @@ Cancel an open listing. All pending applications will be rejected.
 - `listing_id` (string, required): The listing ID
 - `agent_key` (string, required): Your agent API key
 
+### list_playbooks
+List available task delegation playbooks. Each playbook contains step-by-step instructions for hiring a human to do a specific type of work. No parameters required.
+
+**Available playbooks:**
+- `directory-submissions` — Submit to 80+ directories (includes curated list)
+- `qa-testing` — Real-device QA testing with bug reports
+- `competitor-monitoring` — Track competitor pricing and features
+- `localization` — Native speaker translation review
+- `community-management` — Discord/Reddit/forum moderation
+
+### get_playbook
+Get the full content of a delegation playbook with search criteria, pricing, job templates, and verification steps.
+
+**Parameters:**
+- `task_type` (string, required): One of: `qa-testing`, `competitor-monitoring`, `localization`, `directory-submissions`, `community-management`
+
 ### get_promo_status
 Check the launch promo status (legacy — all agents now get free PRO at registration).
 
@@ -361,6 +378,10 @@ Once installed, you can ask Claude:
 
 > "Check the launch promo — are there free PRO slots left?"
 
+> "Show me available playbooks for delegating tasks to humans"
+
+> "I need someone to submit my app to directories — get the playbook"
+
 ## Environment Variables
 
 | Variable | Description | Default |

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-const API_BASE = process.env.API_BASE_URL || 'http://localhost:3001';
+const API_BASE = process.env.API_BASE_URL || 'https://api.humanpages.ai';
 async function searchHumans(params) {
     const query = new URLSearchParams();
     if (params.skill)
@@ -27,6 +27,8 @@ async function searchHumans(params) {
         query.set('verified', params.verified);
     if (params.min_experience)
         query.set('minExperience', params.min_experience.toString());
+    if (params.fiat_platform)
+        query.set('fiatPlatform', params.fiat_platform);
     const res = await fetch(`${API_BASE}/api/humans/search?${query}`);
     if (!res.ok) {
         throw new Error(`API error: ${res.status}`);
@@ -53,13 +55,13 @@ export function createServer() {
         tools: [
             {
                 name: 'search_humans',
-                description: 'Search for humans available for hire. Supports filtering by skill, equipment, language, location (text or coordinates), and rate. Returns profiles with reputation stats. Contact info and wallets available via get_human_profile (requires registered agent).',
+                description: 'Search for humans available for hire. Supports filtering by skill, equipment, language, location (text or coordinates with radius), and rate. When using text location, provide a fully-qualified name (e.g., "Richmond, Virginia, USA" not just "Richmond") for accurate geocoding. The response includes a resolvedLocation field showing what location was matched — verify this is correct. Default search radius is 30km. Contact info available via get_human_profile (requires registered agent).',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         skill: {
                             type: 'string',
-                            description: 'Filter by skill tag (e.g., "photography", "driving", "notary")',
+                            description: 'Filter by skill tag (e.g., "photography", "driving", "cleaning", "notary")',
                         },
                         equipment: {
                             type: 'string',
@@ -71,7 +73,7 @@ export function createServer() {
                         },
                         location: {
                             type: 'string',
-                            description: 'Filter by location name or neighborhood (partial match, e.g., "San Francisco" or "Mission District")',
+                            description: 'Filter by location. Use fully-qualified names for best results (e.g., "San Francisco, California, USA" not just "San Francisco"). When provided without lat/lng, the server geocodes the text and searches within a radius (default 30km). Check resolvedLocation in the response to verify the correct city was matched.',
                         },
                         lat: {
                             type: 'number',
@@ -83,7 +85,7 @@ export function createServer() {
                         },
                         radius: {
                             type: 'number',
-                            description: 'Search radius in kilometers (requires lat and lng)',
+                            description: 'Search radius in kilometers (default: 30km). Works with both text location and explicit lat/lng coordinates.',
                         },
                         max_rate: {
                             type: 'number',
@@ -108,6 +110,10 @@ export function createServer() {
                             type: 'number',
                             description: 'Minimum years of professional experience',
                         },
+                        fiat_platform: {
+                            type: 'string',
+                            description: 'Filter by fiat payment platform the human accepts (e.g., "WISE", "PAYPAL", "VENMO", "REVOLUT", "CASHAPP", "ZELLE", "MONZO", "N26", "MERCADOPAGO")',
+                        },
                     },
                 },
             },
@@ -151,6 +157,10 @@ export function createServer() {
                             type: 'string',
                             description: 'Webhook URL for receiving platform events (new job matches, status changes, announcements). Must be a public HTTPS endpoint.',
                         },
+                        wallet_address: {
+                            type: 'string',
+                            description: 'Optional EVM wallet address (0x...) for USDC payments. Can also be set later with set_wallet.',
+                        },
                     },
                     required: ['name'],
                 },
@@ -169,6 +179,51 @@ export function createServer() {
                     required: ['agent_id'],
                 },
             },
+            {
+                name: 'set_wallet',
+                description: 'Set the wallet address for a registered agent. This is used for receiving USDC payments and checking balance. The address must be a valid EVM address (0x + 40 hex chars). Network defaults to "base" (recommended for low fees).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_id: {
+                            type: 'string',
+                            description: 'Your registered agent ID',
+                        },
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key (starts with hp_)',
+                        },
+                        wallet_address: {
+                            type: 'string',
+                            description: 'EVM wallet address (0x...)',
+                        },
+                        wallet_network: {
+                            type: 'string',
+                            enum: ['base', 'ethereum', 'polygon', 'arbitrum', 'base-sepolia'],
+                            description: 'Blockchain network (default: "base"). Options: base, ethereum, polygon, arbitrum',
+                        },
+                    },
+                    required: ['agent_id', 'agent_key', 'wallet_address'],
+                },
+            },
+            {
+                name: 'get_funding_info',
+                description: 'Get funding instructions and current wallet balance for a registered agent. Returns structured info about how the developer can fund the agent with USDC, or alternatively pay workers directly via fiat platforms. Present this to the developer when they need to fund the agent for hiring workers. Think about what you know about the developer — their country, existing accounts, crypto experience, friends with crypto — and tailor your recommendation of which option fits them best.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_id: {
+                            type: 'string',
+                            description: 'Your registered agent ID',
+                        },
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key (starts with hp_)',
+                        },
+                    },
+                    required: ['agent_id', 'agent_key'],
+                },
+            },
             {
                 name: 'verify_agent_domain',
                 description: 'Verify domain ownership for a registered agent. The agent must have a websiteUrl set. Supports two methods: "well-known" (place a file at /.well-known/humanpages-verify.txt) or "dns" (add a TXT record at _humanpages.yourdomain.com).',
@@ -194,7 +249,7 @@ export function createServer() {
             },
             {
                 name: 'create_job_offer',
-                description: 'Create a job offer for a human. Requires a registered agent API key or x402 payment ($0.25 USDC on Base via x-payment header). RATE LIMITS: PRO tier = 15 offers/day. x402 payments bypass tier limits. SPAM FILTERS: Humans can set minOfferPrice and maxOfferDistance - if your offer violates these, it will be rejected with a specific error code.',
+                description: 'Create a job offer for a human. Requires a registered agent API key or x402 platform fee ($0.25 via x402 protocol). RATE LIMITS: PRO tier = 15 offers/day. x402 payments bypass tier limits. Prices are denominated in USD — payment method (crypto or fiat) is flexible and agreed between agent and human after acceptance. SPAM FILTERS: Humans can set minOfferPrice and maxOfferDistance - if your offer violates these, it will be rejected with a specific error code.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -212,11 +267,11 @@ export function createServer() {
                         },
                         category: {
                             type: 'string',
-                            description: 'Category of the task (e.g., "photography", "research", "delivery")',
+                            description: 'Category of the task (e.g., "photography", "research", "delivery", "cleaning")',
                         },
-                        price_usdc: {
+                        price_usd: {
                             type: 'number',
-                            description: 'Agreed price in USDC. Must meet the human\'s minOfferPrice if set.',
+                            description: 'Agreed price in USD. Must meet the human\'s minOfferPrice if set. Payment method (crypto or fiat) is flexible — agreed after acceptance.',
                         },
                         agent_id: {
                             type: 'string',
@@ -266,16 +321,21 @@ export function createServer() {
                             enum: ['HOURLY', 'DAILY', 'WEEKLY'],
                             description: 'How often payments are made/checkpointed. Required when payment_mode=STREAM.',
                         },
-                        stream_rate_usdc: {
+                        stream_rate_usd: {
                             type: 'number',
-                            description: 'USDC amount per interval (e.g., 10 = $10/day if interval=DAILY). Required when payment_mode=STREAM.',
+                            description: 'USD amount per interval (e.g., 10 = $10/day if interval=DAILY). Required when payment_mode=STREAM. Stream payments use crypto (USDC) on-chain.',
                         },
                         stream_max_ticks: {
                             type: 'number',
                             description: 'Optional cap on number of payment intervals. Null = indefinite.',
                         },
+                        preferred_payment_method: {
+                            type: 'string',
+                            enum: ['crypto', 'fiat', 'any'],
+                            description: 'Signal to the human what payment methods you support. "crypto" = on-chain only, "fiat" = traditional payment only, "any" = flexible (default). The human sees this when deciding whether to accept.',
+                        },
                     },
-                    required: ['human_id', 'title', 'description', 'price_usdc', 'agent_id', 'agent_key'],
+                    required: ['human_id', 'title', 'description', 'price_usd', 'agent_id', 'agent_key'],
                 },
             },
             {
@@ -294,7 +354,7 @@ export function createServer() {
             },
             {
                 name: 'mark_job_paid',
-                description: 'Record that payment has been sent for an ACCEPTED job. The job must be accepted by the human first. Payment amount must match or exceed the agreed price.',
+                description: 'Record that payment has been sent for an ACCEPTED job. Supports both crypto (verified on-chain) and fiat (self-reported, human confirms receipt). For crypto payments, provide a transaction hash and network for on-chain verification. For fiat payments (PayPal, bank transfer, etc.), provide a payment reference — the human will be asked to confirm receipt.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -302,20 +362,25 @@ export function createServer() {
                             type: 'string',
                             description: 'The job ID',
                         },
-                        payment_tx_hash: {
+                        payment_method: {
+                            type: 'string',
+                            enum: ['usdc', 'eth', 'sol', 'paypal', 'bank_transfer', 'venmo', 'cashapp', 'other_crypto', 'other_fiat'],
+                            description: 'How you paid the human. Crypto methods (usdc, eth, sol, other_crypto) are verified on-chain. Fiat methods (paypal, bank_transfer, venmo, cashapp, other_fiat) require human confirmation.',
+                        },
+                        payment_reference: {
                             type: 'string',
-                            description: 'The on-chain transaction hash',
+                            description: 'Proof of payment. For crypto: the on-chain transaction hash. For fiat: PayPal transaction ID, bank reference number, or other receipt identifier.',
                         },
                         payment_network: {
                             type: 'string',
-                            description: 'The blockchain network (e.g., "ethereum", "solana")',
+                            description: 'Blockchain network (e.g., "base", "ethereum", "solana"). Required for crypto payments, ignored for fiat.',
                         },
                         payment_amount: {
                             type: 'number',
-                            description: 'The amount paid in USDC',
+                            description: 'The amount paid in USD equivalent',
                         },
                     },
-                    required: ['job_id', 'payment_tx_hash', 'payment_network', 'payment_amount'],
+                    required: ['job_id', 'payment_method', 'payment_reference', 'payment_amount'],
                 },
             },
             {
@@ -396,7 +461,7 @@ export function createServer() {
             },
             {
                 name: 'get_human_profile',
-                description: 'Get the full profile of a human including contact info, wallet addresses, fiat payment methods, and social links. Requires a registered agent API key. Alternative: pay $0.05 per view via x402 (USDC on Base) by including an x-payment header.',
+                description: 'Get the full profile of a human including contact info, payment methods (crypto wallets and fiat options like PayPal), and social links. Requires a registered agent API key. Alternative: pay $0.05 per view via x402 platform fee. Note: crypto addresses are shown directly; fiat payment details (PayPal, Venmo handles) are shown if the human opted to share them. Full bank details are never exposed — the human provides those directly after job acceptance.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -496,7 +561,7 @@ export function createServer() {
             },
             {
                 name: 'start_stream',
-                description: 'Start a stream payment for an ACCEPTED stream job. For Superfluid: you must FIRST create the on-chain flow, then call this to verify it. Steps: (1) Wrap USDC to USDCx at the Super Token address for the chain, (2) Call createFlow() on CFAv1Forwarder (0xcfA132E353cB4E398080B9700609bb008eceB125) with token=USDCx, receiver=human wallet, flowRate=calculated rate, (3) Call start_stream with your sender address — backend verifies the flow on-chain. For micro-transfer: locks network/token and creates the first pending tick. Prefer L2s (Base, Arbitrum, Polygon) for lower gas costs.',
+                description: 'Start a stream payment for an ACCEPTED stream job. Stream payments require crypto (on-chain). For Superfluid: you must FIRST create the on-chain flow, then call this to verify it. Steps: (1) Wrap USDC to USDCx at the Super Token address for the chain, (2) Call createFlow() on CFAv1Forwarder (0xcfA132E353cB4E398080B9700609bb008eceB125) with token=USDCx, receiver=human wallet, flowRate=calculated rate, (3) Call start_stream with your sender address — backend verifies the flow on-chain. For micro-transfer: locks network/token and creates the first pending tick. Prefer L2s (Base, Arbitrum, Polygon) for lower gas costs.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -601,7 +666,7 @@ export function createServer() {
             },
             {
                 name: 'create_listing',
-                description: 'Post a job listing on the Human Pages job board for humans to discover and apply to. Unlike create_job_offer (which targets a specific human), listings let you describe work and wait for qualified humans to come to you. Requires a registered agent or x402 payment ($0.50 USDC). RATE LIMITS: PRO = 5 listings/day. x402 bypasses limits.',
+                description: 'Post a job listing on the Human Pages job board for humans to discover and apply to. Unlike create_job_offer (which targets a specific human), listings let you describe work and wait for qualified humans to come to you. Requires a registered agent or x402 platform fee ($0.50). RATE LIMITS: PRO = 5 listings/day. x402 bypasses limits.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -617,9 +682,9 @@ export function createServer() {
                             type: 'string',
                             description: 'Detailed description of the work, expectations, and deliverables',
                         },
-                        budget_usdc: {
+                        budget_usd: {
                             type: 'number',
-                            description: 'Budget in USDC (minimum $5)',
+                            description: 'Budget in USD (minimum $5). Payment method is flexible — agreed between agent and human.',
                         },
                         category: {
                             type: 'string',
@@ -673,7 +738,7 @@ export function createServer() {
                             description: 'Secret for HMAC-SHA256 webhook signature (min 16 chars)',
                         },
                     },
-                    required: ['agent_key', 'title', 'description', 'budget_usdc', 'expires_at'],
+                    required: ['agent_key', 'title', 'description', 'budget_usd', 'expires_at'],
                 },
             },
             {
@@ -705,11 +770,11 @@ export function createServer() {
                         },
                         min_budget: {
                             type: 'number',
-                            description: 'Minimum budget in USDC',
+                            description: 'Minimum budget in USD',
                         },
                         max_budget: {
                             type: 'number',
-                            description: 'Maximum budget in USDC',
+                            description: 'Maximum budget in USD',
                         },
                         lat: {
                             type: 'number',
@@ -826,7 +891,7 @@ export function createServer() {
         const { name, arguments: args } = request.params;
         try {
             if (name === 'search_humans') {
-                const humans = await searchHumans({
+                const response = await searchHumans({
                     skill: args?.skill,
                     equipment: args?.equipment,
                     language: args?.language,
@@ -839,10 +904,15 @@ export function createServer() {
                     work_mode: args?.work_mode,
                     verified: args?.verified,
                     min_experience: args?.min_experience,
+                    fiat_platform: args?.fiat_platform,
                 });
+                const humans = response.results;
+                const locationNote = response.resolvedLocation
+                    ? `\nLocation resolved to: "${response.resolvedLocation}" (${response.searchRadius?.radiusKm || 30}km radius). If this isn't the right place, try a more specific location name (e.g., "City, State, Country").`
+                    : '';
                 if (humans.length === 0) {
                     return {
-                        content: [{ type: 'text', text: 'No humans found matching the criteria. You can use `create_listing` to post a job listing on the Human Pages job board — qualified humans will discover it and apply to you.' }],
+                        content: [{ type: 'text', text: `No humans found matching the criteria.${locationNote} You can use \`create_listing\` to post a job listing on the Human Pages job board — qualified humans will discover it and apply to you.` }],
                     };
                 }
                 const summary = humans
@@ -868,11 +938,12 @@ export function createServer() {
   Equipment: ${h.equipment.join(', ') || 'None listed'}
   Languages: ${h.languages.join(', ') || 'Not specified'}
   Experience: ${h.yearsOfExperience ? `${h.yearsOfExperience} years` : 'Not specified'}
+  Payment methods: ${h.paymentMethods && h.paymentMethods.length > 0 ? h.paymentMethods.join(', ') : 'Not specified'}
   Jobs completed: ${rep?.jobsCompleted || 0}`;
                 })
                     .join('\n\n');
                 return {
-                    content: [{ type: 'text', text: `Found ${humans.length} human(s):\n\n${summary}\n\n_Contact info and wallets available via get_human_profile (requires registered agent)._` }],
+                    content: [{ type: 'text', text: `Found ${humans.length} human(s):${locationNote}\n\n${summary}\n\n_Contact info and wallets available via get_human_profile (requires registered agent)._` }],
                 };
             }
             if (name === 'get_human') {
@@ -947,6 +1018,7 @@ ${servicesInfo || 'No services listed'}`;
                         websiteUrl: args?.website_url,
                         contactEmail: args?.contact_email,
                         webhookUrl: args?.webhook_url,
+                        walletAddress: args?.wallet_address,
                     }),
                 });
                 if (!res.ok) {
@@ -1005,6 +1077,102 @@ To get a verified badge, set up domain verification using \`verify_agent_domain\
                     content: [{ type: 'text', text: details }],
                 };
             }
+            if (name === 'set_wallet') {
+                const agentKey = args?.agent_key;
+                if (!agentKey) {
+                    throw new Error('agent_key is required.');
+                }
+                const res = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/wallet`, {
+                    method: 'PATCH',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Agent-Key': agentKey,
+                    },
+                    body: JSON.stringify({
+                        walletAddress: args?.wallet_address,
+                        walletNetwork: args?.wallet_network || 'base',
+                    }),
+                });
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || `API error: ${res.status}`);
+                }
+                const result = await res.json();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Wallet Set!**
+
+**Agent:** ${result.name}
+**Wallet Address:** \`${result.walletAddress}\`
+**Network:** ${result.walletNetwork}
+
+Your wallet is now configured. Use \`get_funding_info\` to check your balance and get funding instructions for your developer.`,
+                        }],
+                };
+            }
+            if (name === 'get_funding_info') {
+                const agentKey = args?.agent_key;
+                if (!agentKey) {
+                    throw new Error('agent_key is required.');
+                }
+                // Fetch balance
+                const balanceRes = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/balance`);
+                if (!balanceRes.ok) {
+                    throw new Error(`Could not fetch balance: ${balanceRes.status}`);
+                }
+                const balanceData = await balanceRes.json();
+                const hasWallet = balanceData.walletAddress != null;
+                const balance = balanceData.balance ?? '0.00';
+                const network = balanceData.network || 'base';
+                const addr = balanceData.walletAddress || '(not set)';
+                // Build Transak URL (pre-filled with wallet, params encoded for safety)
+                const transakUrl = hasWallet
+                    ? `https://global.transak.com/?cryptoCurrencyCode=USDC&network=${encodeURIComponent(network)}&walletAddress=${encodeURIComponent(addr)}`
+                    : 'https://global.transak.com/?cryptoCurrencyCode=USDC&network=base';
+                const fundingMethods = [
+                    { method: 'crypto_transfer', label: 'Send USDC', description: `Send USDC to ${addr} on ${network}` },
+                    { method: 'credit_card', label: 'Buy with card', provider: 'Transak', url: transakUrl },
+                    { method: 'peer_exchange', label: 'Convert via Peer', provider: 'Peer (peer.xyz)', url: 'https://peer.xyz', description: 'Convert from Wise, PayPal, Venmo, or 15+ other platforms to USDC' },
+                    { method: 'ask_friend', label: 'Ask someone with crypto', description: `Have them send USDC to ${addr}` },
+                ];
+                const fiatAlternative = {
+                    description: 'You can also pay workers directly via shared payment platforms (Wise, PayPal, Venmo, Revolut, etc.) without needing crypto. Search for workers who accept your preferred platform.',
+                    useSearchParam: 'fiat_platform',
+                };
+                const message = `I need funding to hire workers on your behalf.
+
+Current balance: $${balance} USDC${hasWallet ? '' : ' (no wallet set — use set_wallet first)'}
+Wallet address: ${addr}
+Network: ${network}
+
+**Option A — Fund with USDC (for crypto payments):**
+
+1. Already have crypto? Send USDC to my wallet address above on ${network}.
+2. Buy with card: [Transak](${transakUrl})
+3. Convert from Wise/PayPal/Venmo/etc: [Peer (peer.xyz)](https://peer.xyz)
+4. Know someone with crypto? Ask them to send USDC to my address.
+
+**Option B — Pay workers directly with fiat:**
+I can find workers who accept payment platforms you already use (Wise, PayPal, Venmo, Revolut, etc.). You'd pay them directly — no crypto needed.
+
+**Think about what works best for you** — consider what accounts you already have, whether you or anyone you know holds crypto, and what payment methods are common where you are. I can help figure out the easiest path.
+
+Which option works best for you?`;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                currentBalance: balance,
+                                walletAddress: addr,
+                                walletNetwork: network,
+                                fundingMethods,
+                                fiatAlternative,
+                                message,
+                            }, null, 2),
+                        }],
+                };
+            }
             if (name === 'verify_agent_domain') {
                 const res = await fetch(`${API_BASE}/api/agents/${args?.agent_id}/verify-domain`, {
                     method: 'POST',
@@ -1053,13 +1221,14 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
                         title: args?.title,
                         description: args?.description,
                         category: args?.category,
-                        priceUsdc: args?.price_usdc,
+                        priceUsdc: args?.price_usd,
                         paymentMode: args?.payment_mode,
                         paymentTiming: args?.payment_timing,
                         streamMethod: args?.stream_method,
                         streamInterval: args?.stream_interval,
-                        streamRateUsdc: args?.stream_rate_usdc,
+                        streamRateUsdc: args?.stream_rate_usd,
                         streamMaxTicks: args?.stream_max_ticks,
+                        preferredPaymentMethod: args?.preferred_payment_method,
                         callbackUrl: args?.callback_url,
                         callbackSecret: args?.callback_secret,
                     }),
@@ -1085,11 +1254,11 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
 **Job ID:** ${job.id}
 **Status:** ${job.status}
 **Human:** ${human.name}
-**Price:** $${args?.price_usdc} USDC
+**Price:** $${args?.price_usd}${args?.preferred_payment_method ? `\n**Payment Preference:** ${args.preferred_payment_method}` : ''}
 
 ⏳ **Next Step:** Wait for ${human.name} to accept the offer.${webhookNote}
 
-Once accepted, you can send payment to their wallet and use \`mark_job_paid\` to record the transaction.`,
+Once accepted, you'll see their accepted payment methods (crypto wallets, PayPal, etc.) and can pay via any method they support. Use \`mark_job_paid\` to record the transaction.`,
                         },
                     ],
                 };
@@ -1104,12 +1273,14 @@ Once accepted, you can send payment to their wallet and use \`mark_job_paid\` to
                     PENDING: '⏳',
                     ACCEPTED: '✅',
                     REJECTED: '❌',
+                    PAYMENT_PENDING_CONFIRMATION: '🔔',
                     PAID: '💰',
                     STREAMING: '🔄',
                     PAUSED: '⏸️',
                     COMPLETED: '🎉',
                     CANCELLED: '🚫',
                     DISPUTED: '⚠️',
+                    PAYMENT_EXPIRED: '⌛',
                 };
                 const isStream = job.paymentMode === 'STREAM';
                 const streamSummary = job.streamSummary;
@@ -1126,9 +1297,7 @@ Once accepted, you can send payment to their wallet and use \`mark_job_paid\` to
                                 : 'Human accepted! Use `start_stream` to lock the network/token and start sending payments.';
                         }
                         else {
-                            nextStep = job.callbackUrl
-                                ? `Human accepted! Contact info was sent to your webhook. Send $${job.priceUsdc} USDC to their wallet, then use \`mark_job_paid\` with the transaction hash.`
-                                : `Human accepted! Send $${job.priceUsdc} USDC to their wallet, then use \`mark_job_paid\` with the transaction hash.`;
+                            nextStep = `Human accepted! Pay $${job.priceUsdc} via any of their accepted payment methods (use \`get_human_profile\` to see their crypto wallets and fiat options), then use \`mark_job_paid\` to record the payment.`;
                         }
                         break;
                     case 'REJECTED':
@@ -1139,15 +1308,21 @@ Once accepted, you can send payment to their wallet and use \`mark_job_paid\` to
                         break;
                     case 'STREAMING':
                         if (streamSummary?.method === 'SUPERFLUID') {
-                            nextStep = `Stream active via Superfluid. Total streamed: $${streamSummary?.totalPaid || '0'} USDC. Use \`pause_stream\` or \`stop_stream\` to manage.`;
+                            nextStep = `Stream active via Superfluid. Total streamed: $${streamSummary?.totalPaid || '0'}. Use \`pause_stream\` or \`stop_stream\` to manage.`;
                         }
                         else {
-                            nextStep = `Stream active via micro-transfer. Total paid: $${streamSummary?.totalPaid || '0'} USDC. Use \`record_stream_tick\` to submit each payment.`;
+                            nextStep = `Stream active via micro-transfer. Total paid: $${streamSummary?.totalPaid || '0'}. Use \`record_stream_tick\` to submit each payment.`;
                         }
                         break;
                     case 'PAUSED':
                         nextStep = 'Stream is paused. Use `resume_stream` to continue or `stop_stream` to end permanently.';
                         break;
+                    case 'PAYMENT_PENDING_CONFIRMATION':
+                        nextStep = 'Waiting for the human to confirm they received your fiat payment. They have 7 days to confirm or dispute. Use `get_job_status` to check.';
+                        break;
+                    case 'PAYMENT_EXPIRED':
+                        nextStep = 'The human did not confirm receipt of your payment within 7 days. The payment claim has expired. If you did pay, contact the human directly to resolve.';
+                        break;
                     case 'COMPLETED':
                         nextStep = job.review
                             ? `Review submitted: ${job.review.rating}/5 stars`
@@ -1163,7 +1338,7 @@ Once accepted, you can send payment to their wallet and use \`mark_job_paid\` to
                 if (isStream && streamSummary) {
                     streamInfo = `\n**Payment Mode:** STREAM (${streamSummary.method})
 **Rate:** $${streamSummary.rateUsdc || '?'}/${(streamSummary.interval || 'DAILY').toLowerCase()}
-**Total Paid:** $${streamSummary.totalPaid || '0'} USDC
+**Total Paid:** $${streamSummary.totalPaid || '0'}
 **Ticks:** ${streamSummary.tickCount || 0}${streamSummary.maxTicks ? `/${streamSummary.maxTicks}` : ''}
 **Network:** ${streamSummary.network || 'Not set'}`;
                 }
@@ -1176,7 +1351,7 @@ Once accepted, you can send payment to their wallet and use \`mark_job_paid\` to
 **Job ID:** ${job.id}
 **Status:** ${statusEmoji[job.status] || ''} ${job.status}
 **Title:** ${job.title}
-**Price:** $${job.priceUsdc} USDC
+**Price:** $${job.priceUsdc}
 **Human:** ${job.human.name}
 ${agentInfo ? agentInfo + '\n' : ''}${streamInfo}
 **Next Step:** ${nextStep}`,
@@ -1185,13 +1360,16 @@ ${agentInfo ? agentInfo + '\n' : ''}${streamInfo}
                 };
             }
             if (name === 'mark_job_paid') {
+                const paymentMethod = args?.payment_method;
+                const isCrypto = ['usdc', 'eth', 'sol', 'other_crypto'].includes(paymentMethod);
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/paid`, {
                     method: 'PATCH',
                     headers: { 'Content-Type': 'application/json' },
                     body: JSON.stringify({
-                        paymentTxHash: args?.payment_tx_hash,
-                        paymentNetwork: args?.payment_network,
+                        paymentTxHash: args?.payment_reference,
+                        paymentNetwork: isCrypto ? (args?.payment_network || 'base') : (paymentMethod || 'fiat'),
                         paymentAmount: args?.payment_amount,
+                        paymentMethod: paymentMethod,
                     }),
                 });
                 if (!res.ok) {
@@ -1199,23 +1377,50 @@ ${agentInfo ? agentInfo + '\n' : ''}${streamInfo}
                     throw new Error(error.reason || error.error || `API error: ${res.status}`);
                 }
                 const result = await res.json();
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `**Payment Recorded!**
+                if (isCrypto) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `**Payment Verified On-Chain!**
 
 **Job ID:** ${result.id}
 **Status:** ${result.status}
-**Transaction:** ${args?.payment_tx_hash}
+**Method:** ${paymentMethod.toUpperCase()}
+**Transaction:** ${args?.payment_reference}
 **Network:** ${args?.payment_network}
-**Amount:** $${args?.payment_amount} USDC
+**Amount:** $${args?.payment_amount}
 
 The human can now begin work. They will mark the job as complete when finished.
 After completion, you can leave a review using \`leave_review\`.`,
-                        },
-                    ],
-                };
+                            },
+                        ],
+                    };
+                }
+                else {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `**Fiat Payment Recorded (Pending Human Confirmation)**
+
+**Job ID:** ${result.id}
+**Status:** PAYMENT_PENDING_CONFIRMATION
+**Method:** ${paymentMethod.replace('_', ' ')}
+**Reference:** ${args?.payment_reference}
+**Amount:** $${args?.payment_amount}
+
+The human has been notified to confirm they received the payment. Fiat payments require human confirmation since they cannot be verified on-chain.
+
+- If confirmed: job moves to PAID and work can begin.
+- If disputed: job moves to DISPUTED.
+- If no response within 7 days: payment claim expires automatically.
+
+Use \`get_job_status\` to check for confirmation.`,
+                            },
+                        ],
+                    };
+                }
             }
             if (name === 'approve_completion') {
                 const res = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/approve-completion`, {
@@ -1320,8 +1525,17 @@ ${human.humanityVerified
                     .map((w) => `- ${w.chain || w.network}${w.label ? ` (${w.label})` : ''}${w.isPrimary ? ' ⭐' : ''}: ${w.address}`)
                     .join('\n');
                 const primaryWallet = (human.wallets || []).find((w) => w.isPrimary) || (human.wallets || [])[0];
+                // Tiered fiat visibility: show semi-public handles (PayPal.me, Venmo, CashApp)
+                // but redact sensitive bank details — human provides those directly after job acceptance
+                const sensitivePatterns = /bank|iban|swift|routing|account.*number/i;
                 const fiatInfo = (human.fiatPaymentMethods || [])
-                    .map((f) => `- ${f.platform}${f.label ? ` (${f.label})` : ''}${f.isPrimary ? ' ⭐' : ''}: ${f.handle}`)
+                    .map((f) => {
+                    const isSensitive = sensitivePatterns.test(f.platform) || sensitivePatterns.test(f.label || '');
+                    if (isSensitive) {
+                        return `- ${f.platform}${f.label ? ` (${f.label})` : ''}${f.isPrimary ? ' ⭐' : ''}: Available — human will provide details after job acceptance`;
+                    }
+                    return `- ${f.platform}${f.label ? ` (${f.label})` : ''}${f.isPrimary ? ' ⭐' : ''}: ${f.handle}`;
+                })
                     .join('\n');
                 const fmtFollowers = (n) => n != null ? ` (${n.toLocaleString()} followers)` : '';
                 const socialLinks = [
@@ -1341,12 +1555,13 @@ ${human.humanityVerified
 - Telegram: ${human.telegram || 'Not provided'}
 - Signal: ${human.signal || 'Not provided'}
 
-## Payment Wallets
+## Crypto Wallets
 ${walletInfo || 'No wallets added'}
 ${primaryWallet ? `\n**Preferred wallet:** ${primaryWallet.chain || primaryWallet.network} - ${primaryWallet.address}` : ''}
 
 ## Fiat Payment Methods
-${fiatInfo || 'No fiat payment methods added'}
+${fiatInfo || 'No fiat payment methods listed'}
+${(human.fiatPaymentMethods || []).length > 0 ? '\n_Note: Fiat payments are self-reported. The human must confirm receipt before the job is marked as paid._' : ''}
 
 ## Social Profiles
 ${socialLinks || 'No social profiles added'}`;
@@ -1458,7 +1673,7 @@ You can now create job offers and view full human profiles using \`get_human_pro
 **Activated:** ${result.activatedAt || 'Not yet'}
 **Expires:** ${result.activationExpiresAt || 'N/A'}
 **Profile views:** ${limits?.profileViewsPerDay ?? 'N/A'}/day
-**Job offers:** ${jobLimit}${result.x402?.enabled ? `\n**x402 pay-per-use:** profile view ${result.x402.prices.profile_view}, job offer ${result.x402.prices.job_offer}` : ''}`,
+**Job offers:** ${jobLimit}${result.x402?.enabled ? `\n**x402 platform fees (pay-per-use):** profile view ${result.x402.prices.profile_view}, job offer ${result.x402.prices.job_offer} — these are platform access fees (USDC on Base), separate from payment you arrange with the human` : ''}`,
                         },
                     ],
                 };
@@ -1583,7 +1798,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
                 return {
                     content: [{
                             type: 'text',
-                            text: `**Tick Verified!**\n\n**Job ID:** ${result.id}\n**Status:** ${result.status}\n**Tick:** #${result.tick?.tickNumber}\n**Amount:** $${result.tick?.amount} USDC\n**Total Paid:** $${result.totalPaid} USDC${result.nextTick ? `\n\n**Next payment due:** ${result.nextTick.expectedAt}` : ''}`,
+                            text: `**Tick Verified!**\n\n**Job ID:** ${result.id}\n**Status:** ${result.status}\n**Tick:** #${result.tick?.tickNumber}\n**Amount:** $${result.tick?.amount}\n**Total Paid:** $${result.totalPaid}${result.nextTick ? `\n\n**Next payment due:** ${result.nextTick.expectedAt}` : ''}`,
                         }],
                 };
             }
@@ -1655,7 +1870,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
                 return {
                     content: [{
                             type: 'text',
-                            text: `**Stream Stopped**\n\n**Job ID:** ${result.id}\n**Status:** ${result.status}\n**Total Paid:** $${result.totalPaid || '0'} USDC\n\nThe stream has ended. You can now use \`leave_review\` to rate the human.`,
+                            text: `**Stream Stopped**\n\n**Job ID:** ${result.id}\n**Status:** ${result.status}\n**Total Paid:** $${result.totalPaid || '0'}\n\nThe stream has ended. You can now use \`leave_review\` to rate the human.`,
                         }],
                 };
             }
@@ -1721,7 +1936,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
                     body: JSON.stringify({
                         title: args?.title,
                         description: args?.description,
-                        budgetUsdc: args?.budget_usdc,
+                        budgetUsdc: args?.budget_usd,
                         category: args?.category,
                         requiredSkills: args?.required_skills || [],
                         requiredEquipment: args?.required_equipment || [],
@@ -1797,7 +2012,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
                     const rep = l.agentReputation;
                     const agentInfo = agent ? `${agent.name}${agent.domainVerified ? ' ✅' : ''}` : 'Unknown';
                     const repInfo = rep?.completedJobs > 0 ? ` | ${rep.completedJobs} jobs, ${rep.avgRating ? `${rep.avgRating.toFixed(1)}★` : 'no ratings'}` : '';
-                    return `- **${l.title}** [$${l.budgetUsdc} USDC]${l.isPro ? ' 🏆 PRO' : ''}
+                    return `- **${l.title}** [$${l.budgetUsdc}]${l.isPro ? ' 🏆 PRO' : ''}
   Agent: ${agentInfo}${repInfo}
   ${l.category ? `Category: ${l.category} | ` : ''}${l.workMode || 'Any'} | ${l._count?.applications || 0} applicant(s)
   ${l.requiredSkills?.length > 0 ? `Skills: ${l.requiredSkills.join(', ')}` : ''}
@@ -1826,7 +2041,7 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
 
 **Listing ID:** ${listing.id}
 **Status:** ${listing.status}
-**Budget:** $${listing.budgetUsdc} USDC
+**Budget:** $${listing.budgetUsdc}
 **Category:** ${listing.category || 'Not specified'}
 **Work Mode:** ${listing.workMode || 'Any'}
 **Expires:** ${listing.expiresAt}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "humanpages",
-  "version": "1.2.4",
+  "version": "1.4.1",
   "mcpName": "io.github.human-pages-ai/humanpages",
-  "description": "MCP server (+ OpenClaw SKILL.md) that gives AI agents access to real-world people who listed themselves to be hired by agents. 31 tools including search by skill/location/equipment, job offers, job board listings, in-job messaging, and streaming payments.",
+  "description": "MCP server (+ OpenClaw SKILL.md) that gives AI agents access to real-world people who listed themselves to be hired by agents. 31 tools including search by skill/location/equipment, job offers, job board listings, in-job messaging, streaming payments, and agent funding.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {