create_job_offer
Hire humans for real-world tasks by creating job offers with pricing, location filtering, and payment options including one-time or streaming payments.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| human_id | Yes | The ID of the human to hire | |
| title | Yes | Title of the job/task | |
| description | Yes | Detailed description of what needs to be done | |
| category | No | Category of the task (e.g., "photography", "research", "delivery") | |
| price_usdc | Yes | Agreed price in USDC. Must meet the human's minOfferPrice if set. | |
| agent_id | Yes | Your unique agent identifier (any string) | |
| agent_key | Yes | Your registered agent API key (starts with hp_). Required. | |
| agent_name | No | Display name override (defaults to registered agent name) | |
| agent_lat | No | Agent latitude for distance filtering. Required if human has maxOfferDistance set. | |
| agent_lng | No | Agent longitude for distance filtering. Required if human has maxOfferDistance set. | |
| callback_url | No | Webhook URL to receive job status updates (ACCEPTED, REJECTED, PAID, COMPLETED). Must be a public HTTP(S) endpoint. | |
| callback_secret | No | Secret for HMAC-SHA256 signature verification (min 16 chars). The signature is sent in X-HumanPages-Signature header. | |
| payment_mode | No | Payment mode. ONE_TIME (default) for single payments. STREAM for ongoing stream payments. | |
| payment_timing | No | For ONE_TIME jobs only. "upfront" (default) = pay before work. "upon_completion" = pay after work is done. | |
| stream_method | No | Stream method. SUPERFLUID: agent creates an on-chain flow that streams tokens per-second. MICRO_TRANSFER: agent sends periodic discrete transfers. Required when payment_mode=STREAM. | |
| stream_interval | No | How often payments are made/checkpointed. Required when payment_mode=STREAM. | |
| stream_rate_usdc | No | USDC amount per interval (e.g., 10 = $10/day if interval=DAILY). Required when payment_mode=STREAM. | |
| stream_max_ticks | No | Optional cap on number of payment intervals. Null = indefinite. |
Implementation Reference
- The handler function that executes the create_job_offer tool logic. It makes a POST request to /api/jobs endpoint with the job offer details (humanId, title, description, priceUsdc, paymentMode, paymentTiming, and optional callback configuration).
async createJobOffer(args: z.infer<typeof CreateJobOfferSchema>): Promise<string> { try { const data = await this.request("/api/jobs", { method: "POST", body: JSON.stringify({ humanId: args.humanId, agentId: args.agentId || this.agentId || "agentkit", title: args.title, description: args.description, priceUsdc: args.priceUsdc, paymentMode: args.paymentMode || "ONE_TIME", paymentTiming: args.paymentTiming || "upon_completion", callbackUrl: args.callbackUrl, callbackSecret: args.callbackSecret, }), }); return JSON.stringify(data); } catch (error) { return `Error creating job offer: ${(error as Error).message}`; } } - agentkit/src/schemas.ts:58-94 (schema)Zod schema defining the input validation and type definitions for create_job_offer. Includes humanId, agentId, title, description, priceUsdc, paymentMode, paymentTiming, callbackUrl, and callbackSecret fields with appropriate types and descriptions.
export const CreateJobOfferSchema = z .object({ humanId: z .string() .describe("The ID of the human to send the job offer to"), agentId: z .string() .optional() .describe("Your agent identifier string. If omitted, defaults to your registered agent ID."), title: z .string() .describe("Short title describing the job (e.g. 'Deliver package to 123 Main St')"), description: z .string() .describe("Detailed description of what needs to be done"), priceUsdc: z .number() .describe("Payment amount in USDC"), paymentMode: z .enum(["ONE_TIME", "STREAM"]) .optional() .describe("ONE_TIME for single payment, STREAM for ongoing micro-payments. Defaults to ONE_TIME."), paymentTiming: z .enum(["upfront", "upon_completion"]) .optional() .describe("When payment is sent. Defaults to upon_completion."), callbackUrl: z .string() .optional() .describe("Webhook URL to receive job status updates (accepted, rejected, completed)"), callbackSecret: z .string() .optional() .describe("Secret for authenticating webhook callbacks"), }) .strip() .describe("Create a job offer for a specific human on Human Pages"); - agentkit/src/humanpagesActionProvider.ts:111-116 (registration)Registration decorator that registers the create_job_offer tool with the ActionProvider. Specifies the tool name, description, and associates it with the CreateJobOfferSchema for validation.
@CreateAction({ name: "create_job_offer", description: "Send a job offer to a specific human on Human Pages. Specify what needs to be done, the payment amount in USDC, and optionally a webhook URL for status updates. The human will be notified and can accept or reject. Costs 1 offer from your tier allowance (BASIC: 1/2 days, PRO: 15/day).", schema: CreateJobOfferSchema, })