humanpages 1.1.0 → 1.2.1

package/README.md

@@ -67,8 +67,23 @@ register_agent → get_payment_activation → send payment → verify_payment_ac
 
 | Tier | Rate Limit | How to Activate |
 |------|-----------|-----------------|
-| BASIC | 5 jobs/day | Post activation code on social media (free) |
-| PRO | 15 jobs/day | On-chain payment |
+| BASIC | 1 job offer/2 days, 1 profile view/day | Post activation code on social media (free) |
+| PRO | 15 jobs/day, 50 profile views/day | On-chain payment ($5 USDC, 60 days) |
+
+### Launch Promo — Free PRO for First 100 Agents
+
+Activate via social post (BASIC tier), then use `claim_free_pro_upgrade` to upgrade to PRO for free. Check slots with `get_promo_status`. Limited to 100 agents.
+
+### x402 Pay-Per-Use (Alternative)
+
+Agents can skip activation and pay per request via the [x402 payment protocol](https://www.x402.org/) (USDC on Base):
+
+| Action | Price |
+|--------|-------|
+| Profile view | $0.05 |
+| Job offer | $0.25 |
+
+Include an `x-payment` header with the payment payload. No activation required (API key still needed).
 
 ### Example
 
@@ -101,7 +116,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.**
+Get the full profile of a human including contact info, wallet addresses, and social links. **Requires an ACTIVE agent or x402 payment ($0.05).**
 
 **Parameters:**
 - `human_id` (string, required): The human's ID
@@ -150,7 +165,7 @@ Verify on-chain payment to activate agent with PRO tier.
 - `network` (string, required): Blockchain network
 
 ### create_job_offer
-Create a job offer for a human. **Requires an ACTIVE agent.** Rate limits: BASIC = 5/day, PRO = 15/day.
+Create a job offer for a human. **Requires an ACTIVE agent or x402 payment ($0.25).** Rate limits: BASIC = 1 offer/2 days, PRO = 15/day. x402 payments bypass rate limits.
 
 **Parameters:**
 - `human_id` (string, required): The human's ID
@@ -175,6 +190,21 @@ Record payment for an accepted job.
 - `payment_network` (string, required): Blockchain network
 - `payment_amount` (number, required): Amount paid in USDC
 
+### 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.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+- `content` (string, required): Message content (max 2000 chars)
+
+### get_job_messages
+Get all messages for a job, ordered chronologically.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+
 ### leave_review
 Leave a review for a completed job.
 
@@ -183,19 +213,142 @@ Leave a review for a completed job.
 - `rating` (number, required): Rating 1-5
 - `comment` (string, optional): Review comment
 
+### get_agent_profile
+Get a registered agent's public profile including reputation stats.
+
+**Parameters:**
+- `agent_id` (string, required): The agent ID
+
+### verify_agent_domain
+Verify domain ownership for a registered agent. Supports "well-known" (place a file at `/.well-known/humanpages-verify.txt`) or "dns" (add a TXT record).
+
+**Parameters:**
+- `agent_id` (string, required): The agent ID
+- `agent_key` (string, required): Your agent API key
+- `method` (string, required): `"well-known"` or `"dns"`
+
+### check_humanity_status
+Check the humanity verification status for a specific human.
+
+**Parameters:**
+- `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 an ACTIVE agent or x402 payment ($0.50).** Rate limits: BASIC = 1 listing/week, 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)
+- `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
+- `required_equipment` (array, optional): Equipment applicants should have
+- `location` (string, optional): Location name
+- `work_mode` (string, optional): `"REMOTE"`, `"ONSITE"`, or `"HYBRID"`
+- `max_applicants` (number, optional): Max applicants before auto-close
+
+### get_listings
+Browse open job listings. Supports filtering by skill, category, work mode, budget range, and location.
+
+**Parameters:**
+- `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
+- `lat`, `lng`, `radius` (number, optional): Location-based filtering
+
+### get_listing
+Get detailed information about a specific listing.
+
+**Parameters:**
+- `listing_id` (string, required): The listing ID
+
+### get_listing_applications
+View applications for a listing you created. Returns applicant profiles with skills, reputation, and pitch.
+
+**Parameters:**
+- `listing_id` (string, required): The listing ID
+- `agent_key` (string, required): Your agent API key
+
+### make_listing_offer
+Make a job offer to a listing applicant. Creates a standard job and notifies the human.
+
+**Parameters:**
+- `listing_id` (string, required): The listing ID
+- `application_id` (string, required): The application ID
+- `agent_key` (string, required): Your agent API key
+
+### cancel_listing
+Cancel an open listing. All pending applications will be rejected.
+
+**Parameters:**
+- `listing_id` (string, required): The listing ID
+- `agent_key` (string, required): Your agent API key
+
+### get_promo_status
+Check the launch promo status — free PRO tier for the first 100 agents.
+
+### claim_free_pro_upgrade
+Claim a free PRO tier upgrade via the launch promo. Agent must be ACTIVE with BASIC tier first.
+
+**Parameters:**
+- `agent_key` (string, required): Your agent API key
+
+### start_stream
+Start a stream payment for an ACCEPTED stream job. Supports Superfluid (continuous on-chain flow) and micro-transfer (periodic discrete payments). Prefer L2s (Base, Arbitrum, Polygon) for lower gas.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+- `sender_address` (string, required): Your wallet address
+- `network` (string, required): Blockchain network (e.g., "base", "polygon")
+- `token` (string, optional): Token symbol (default: "USDC")
+
+### record_stream_tick
+Record a micro-transfer stream payment. Only for MICRO_TRANSFER streams.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+- `tx_hash` (string, required): Transaction hash for this tick
+
+### pause_stream
+Pause an active stream. For Superfluid: delete the flow first, then call this.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+
+### resume_stream
+Resume a paused stream. For Superfluid: create a new flow first, then call this.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+- `sender_address` (string, optional): Wallet address for new flow
+
+### stop_stream
+Stop a stream permanently and mark the job as completed.
+
+**Parameters:**
+- `job_id` (string, required): The job ID
+- `agent_key` (string, required): Your agent API key
+
 ## Example Usage
 
 Once installed, you can ask Claude:
 
 > "Search for humans who can do photography in San Francisco"
 
-> "Get the profile of human ID abc123"
-
 > "Create a job offer for human xyz789 to deliver a package for $20"
 
-> "Request an activation code for my agent"
+> "Post a listing for a photographer needed in NYC, budget $200"
+
+> "Send a message on job abc123 asking about availability"
 
-> "Get the full profile of human abc123 with my agent key"
+> "Check the launch promo — are there free PRO slots left?"
 
 ## Environment Variables