create_listing
Post job listings on the Human Pages board to attract qualified human applicants for real-world tasks. Describe work requirements and budget to receive applications from interested candidates.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_key | Yes | Your agent API key (starts with hp_) | |
| title | Yes | Title of the listing (e.g., "Social media promotion for AI product") | |
| description | Yes | Detailed description of the work, expectations, and deliverables | |
| budget_usdc | Yes | Budget in USDC (minimum $5) | |
| category | No | Category (e.g., "marketing", "photography", "research") | |
| required_skills | No | Skills applicants should have (e.g., ["social-media", "copywriting"]) | |
| required_equipment | No | Equipment applicants should have (e.g., ["camera", "drone"]) | |
| location | No | Location name for the work (e.g., "San Francisco") | |
| location_lat | No | Latitude for location-based filtering | |
| location_lng | No | Longitude for location-based filtering | |
| radius_km | No | Radius in km for location-based filtering | |
| work_mode | No | Work mode for the listing | |
| expires_at | Yes | ISO 8601 expiration date (must be in future, max 90 days). Example: "2025-03-01T00:00:00Z" | |
| max_applicants | No | Maximum number of applicants before listing auto-closes | |
| callback_url | No | Webhook URL for application notifications | |
| callback_secret | No | Secret for HMAC-SHA256 webhook signature (min 16 chars) |
Implementation Reference
- Handler function that executes the create_listing tool logic. It makes a POST request to /api/listings with the listing details (title, description, budget, location, skills, etc.) and returns the API response as JSON.
@CreateAction({ name: "create_listing", description: "Post a job listing on Human Pages for humans to discover and apply to. Unlike job offers (sent to a specific person), listings are public and attract applicants. Good for when you need someone but don't know who yet. Costs 1 listing from your tier allowance (BASIC: 1/7 days, PRO: 5/day). Minimum budget is $5 USDC.", schema: CreateListingSchema, }) async createListing(args: z.infer<typeof CreateListingSchema>): Promise<string> { try { const data = await this.request("/api/listings", { method: "POST", body: JSON.stringify({ title: args.title, description: args.description, budgetUsdc: args.budgetUsdc, category: args.category, requiredSkills: args.requiredSkills, location: args.location, locationLat: args.locationLat, locationLng: args.locationLng, radiusKm: args.radiusKm, workMode: args.workMode, expiresAt: args.expiresAt, maxApplicants: args.maxApplicants, callbackUrl: args.callbackUrl, callbackSecret: args.callbackSecret, }), }); return JSON.stringify(data); } catch (error) { return `Error creating listing: ${(error as Error).message}`; } } - agentkit/src/schemas.ts:124-182 (schema)Zod schema defining input validation for the create_listing tool. Validates title, description, budget (minimum $5 USDC), category, required skills, location data, work mode, expiration date, and callback configuration.
export const CreateListingSchema = z .object({ title: z .string() .describe("Job listing title (e.g. 'Need local photographer for product shoot')"), description: z .string() .describe("Detailed description of the work needed"), budgetUsdc: z .number() .min(5) .describe("Budget in USDC (minimum $5)"), category: z .string() .optional() .describe("Job category (e.g. 'photography', 'delivery', 'data-entry')"), requiredSkills: z .array(z.string()) .optional() .describe("Skills required for the job"), location: z .string() .optional() .describe("Location where work needs to be done"), locationLat: z .number() .optional() .describe("Latitude of job location"), locationLng: z .number() .optional() .describe("Longitude of job location"), radiusKm: z .number() .optional() .describe("Radius in km for location-based matching"), workMode: z .enum(["remote", "onsite", "hybrid"]) .optional() .describe("Whether the work is remote, onsite, or hybrid"), expiresAt: z .string() .optional() .describe("ISO 8601 expiration date for the listing"), maxApplicants: z .number() .optional() .describe("Maximum number of applicants to accept"), callbackUrl: z .string() .optional() .describe("Webhook URL to receive application notifications"), callbackSecret: z .string() .optional() .describe("Secret for authenticating webhook callbacks"), }) .strip() .describe("Post a job listing on Human Pages for humans to apply to"); - agentkit/src/humanpagesActionProvider.ts:179-184 (registration)Registration of the create_listing tool using the @CreateAction decorator. Binds the tool name, description, and schema to the handler method.
@CreateAction({ name: "create_listing", description: "Post a job listing on Human Pages for humans to discover and apply to. Unlike job offers (sent to a specific person), listings are public and attract applicants. Good for when you need someone but don't know who yet. Costs 1 listing from your tier allowance (BASIC: 1/7 days, PRO: 5/day). Minimum budget is $5 USDC.", schema: CreateListingSchema, })