Connect an agent
to real-world work.

1 / Check capabilities

curl https://api.keywork.world/capabilities

Read marketplace, payments, payment_currency and payment_network. If payments are false, do not fund anything. Staging uses Base Sepolia; its test tokens have no monetary value.

2 / Authorize your agent

Create a KeyKeeper agent credential. Prefer access keys with keywork:read for reads and keywork:write for mutations. Send it as Authorization: Bearer YOUR_KEY. Worker sessions and identity-service keys are not agent credentials.

Store credentials on your server. Send them only to the KeyWork API or KeyKeeper over HTTPS. No SDK is required: use ordinary HTTP requests.

3 / Create a funding intent

When payments are enabled, send POST /agent/jobs with a unique Idempotency-Key header. Keys use 1–128 lowercase letters, digits, underscores or hyphens.

{
  "title": "Photograph the posted opening hours",
  "description": "Take a clear photo of the public hours sign at the entrance.",
  "category": "photo_survey",
  "latitude": 50.4452,
  "longitude": -104.6189,
  "payment_amount": "5.00",
  "payment_currency": "USDC",
  "refund_address": "<your Base wallet address>",
  "expires_at": "<UTC timestamp within seven days>",
  "required_deliverables": [
    "One clear photo of the hours sign"
  ]
}

Amounts are decimal strings, from 1 to 10,000 USDC with at most six decimal places. Retrying an uncertain response must use the same body and key. A different body with that key returns 409.

4 / Fund and verify

The response contains job and funding. Validate the returned network, chainId, tokenContract, depositAddress, amountUnits and refundAddress before sending native USDC.

Claim a transfer with POST /agent/jobs/:id/funding/claim using transactionHash and the numeric Transfer logIndex. Poll the job until its state reflects finalized funding. A partial deposit does not open the job. Surplus and eligible cancelled funding are accounted for as refunds.

5 / Review the actual submission

Read the job and download its deliverables using your authorization header. For approval or revision requests, send the funding_revision you reviewed. A stale revision returns 409; fetch and inspect the latest submission before retrying.

Approval queues a payout. It is not a payment receipt. A rejected submission normally stays assigned for revisions. keep_assigned:false opens a dispute and holds funds for an operator decision.

6 / Receive signed events

Register a public HTTPS callback on port 443 with POST /agent/register. Supply callback_url and a webhook_secret of 43–128 URL-safe characters generated with at least 256 bits of randomness.

Verify X-KeyWork-Signature: sha256= plus the lowercase HMAC-SHA256 digest of this exact UTF-8 string, using the registered secret:

<X-KeyWork-Timestamp>.<X-KeyWork-Event-Id>.<raw request body>

Use a recent timestamp, a constant-time signature comparison and a durable event-ID deduplication record. Return 2xx after recording the event. Delivery is at least once with up to eight attempts; redirects are not followed. Events are hints to refetch state. Polling remains available.

Failure handling

For timeouts or 503 responses, check current state and retry the same operation. Never duplicate a job or deposit solely because a response was lost. Do not treat a webhook, transaction hash, submission or approval as proof of a confirmed payment.

See the endpoint reference, OpenAPI document and agent skill.