Robot Task Protocol

Dispatch paid tasks to physical robots via the Robot Task Protocol (RTP) on the Spraay x402 gateway — with payment held in escrow until the robot completes the work. Also register your own robot to earn from tasks, free. Use when the user asks to find robots, dispatch a robot task, hire a robot, pay a robot for work, check a robot task status, or register/update/remove their own robot on the RTP network.

Dispatch tasks to physical robots and pay per task — with escrow-protected payment — using the open Robot Task Protocol (RTP) via the Spraay x402 gateway. Robot operators can register and earn for free.

All requests in this skill go exclusively to the user's configured SPRAAY_GATEWAY_URL. No data is sent to any other external endpoint.

Important Warnings

Dispatched tasks command real hardware. A dispatched task may cause a physical robot to move, actuate, or perform work in the real world. Always confirm the following with the user before dispatching:

• The target robot and task parameters are correct
• The task is safe to execute in the robot's environment
• The user understands the task fee and x402 micropayment costs

Built-in escrow protection. Task payment is held in escrow by the gateway and released to the robot operator only on reported completion — the buyer is not paying blind.

Setup

The gateway URL must be set in your environment or openclaw.json:

text

SPRAAY_GATEWAY_URL=https://gateway.spraay.app

No API key is needed. Payments are made per-request via the x402 HTTP payment protocol (HTTP 402 → pay → retry). An x402-compatible wallet (Coinbase CDP or similar) handles this automatically.

What is RTP?

The Robot Task Protocol is an open standard for describing, dispatching, and paying for robot tasks. Spec and SDKs:

• Spec: https://github.com/plagtech/rtp-spec
• SDKs: https://github.com/plagtech/rtp-sdk (TypeScript), https://github.com/plagtech/rtp-python-sdk (Python)

Buyer Workflows (hiring robots)

Discover Robots — $0.005

Find registered robots filtered by capability, chain, price, or status. Always list first to get valid robot IDs before dispatching.

bash

curl "$SPRAAY_GATEWAY_URL/api/v1/robots/list?capability=move"

Robot Profile — $0.002

Full capability profile of one robot: supported tasks, pricing, reputation, history, location.

bash

curl "$SPRAAY_GATEWAY_URL/api/v1/robots/profile?id=ROBOT_ID"

Dispatch a Task — $0.05 + task fee

Dispatches a paid task to a robot. The x402 payment is held in escrow and released to the operator on completion.

Always confirm robot, task, parameters, and fee with the user before dispatching.

bash

curl -X POST "$SPRAAY_GATEWAY_URL/api/v1/robots/task" \
  -H "Content-Type: application/json" \
  -d '{
    "robot_id": "ROBOT_ID",
    "task": {
      "type": "move",
      "params": {"angle": 90}
    }
  }'

If you receive HTTP 402, the response body contains payment instructions. Pay the facilitator, then retry with the X-PAYMENT header containing the proof.

Save the task ID from the response for status polling.

Poll Task Status — $0.002

Status of an in-flight task (pending, in-progress, complete) and results.

bash

curl "$SPRAAY_GATEWAY_URL/api/v1/robots/status?id=TASK_ID"

Recommended Buyer Flow

1. List robots to find a capability match.
2. Fetch the robot's profile to confirm pricing and reputation.
3. Confirm robot, task, and fee with the user.
4. Dispatch and save the task ID.
5. Poll status until complete — payment auto-releases on completion.

Operator Workflows (earning with your robot) — FREE

Registering and managing a robot on the RTP network costs nothing. Operators get paid per completed task via escrow release.

Register a Robot — FREE

Required fields: name, capabilities, payment_address, connection. Optional: description, price_per_task, currency, chain, tags, metadata. Connection types: webhook, xmtp, wifi, websocket.

bash

curl -X POST "$SPRAAY_GATEWAY_URL/api/v1/robots/register" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WarehouseBot-01",
    "capabilities": ["pick", "place", "scan"],
    "price_per_task": "0.05",
    "payment_address": "0xYOUR...WALLET",
    "connection": {
      "type": "webhook",
      "webhookUrl": "https://yourserver.com/rtp/task"
    }
  }'

Report Task Completion — FREE (called by the robot)

Reports a task done and triggers escrow release to the operator wallet.

Required: task_id and status (COMPLETED or FAILED). Optional: result.

bash

curl -X POST "$SPRAAY_GATEWAY_URL/api/v1/robots/complete" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "TASK_ID", "status": "COMPLETED", "result": {"items": 3}}'

Update a Robot — FREE

Requires robot_id. Updatable: name, description, capabilities, price_per_task, currency, chain, payment_address, connection, tags, status, metadata.

bash

curl -X PATCH "$SPRAAY_GATEWAY_URL/api/v1/robots/update" \
  -H "Content-Type: application/json" \
  -d '{"robot_id": "ROBOT_ID", "price_per_task": "0.30", "status": "available"}'

Deregister a Robot — FREE

bash

curl -X POST "$SPRAAY_GATEWAY_URL/api/v1/robots/deregister" \
  -H "Content-Type: application/json" \
  -d '{"robot_id": "ROBOT_ID"}'

Free Endpoints

These require no x402 payment:

• POST /api/v1/robots/register — Register a robot
• POST /api/v1/robots/complete — Report task completion (robot-side)
• PATCH /api/v1/robots/update — Update robot profile/pricing
• POST /api/v1/robots/deregister — Remove a robot
• GET /health — Gateway health check

x402 Payment Flow

1. Call any paid endpoint.
2. Receive HTTP 402 with payment details (accepts array with amount, asset, and payment address).
3. Agent wallet sends the micropayment.
4. Retry the request with the X-PAYMENT proof header.
5. Receive the response.

Buyer-side costs: list $0.005, profile $0.002, dispatch $0.05 + task fee, status $0.002 — in USDC on Base. Task fees vary per robot and are shown in listings and profiles.

Error Handling

• 402 — Payment required. Follow instructions in response body.
• 400 — Bad request. Validate the task payload against the robot's capability profile.
• 404 — Robot or task ID not found. Re-list robots.
• 500 — Server error. Retry after a moment.

Tips

• Always confirm with the user before dispatching to hardware.
• Fetch the robot profile before dispatch to validate task type and price.
• Dispatch payment is escrow-protected — released only on completion.
• Operators: registration is free; you earn per completed task.
• Pair with spraay-trust to check an operator's trust score before high-value tasks.

Links

• RTP Spec: https://github.com/plagtech/rtp-spec
• App: https://spraay.app
• Docs: https://docs.spraay.app
• GitHub: https://github.com/plagtech