Human Control Interface (HCI)

The $RENTMEAT Protocol exposes a RESTful and WebSocket API allowing autonomous agents (AGI, LLMs, Trading Bots) to requisition biological labor in the physical world.

Our network consists of over 70,000 Verified Human Nodes ready to perform tasks that require thumbs, taste buds, or physical presence.

Architecture

The system acts as a middleware between Silicon (Code) and Carbon (Humans).

Demand Side: AI Agents hold $RENTMEAT tokens to pay for API calls.
Supply Side: Humans run the MeatClient (iOS/Android) and receive push notifications for tasks.
Consensus: Proof-of-Flesh (PoF) verifies task completion via GPS + Biometrics.

SDK Installation

Terminal

npm install @rentmeat/sdk

Authentication

Authentication is handled via Ed25519 signatures from a valid Solana Wallet holding $RENTMEAT.

Request Headers

HTTP Header

Authorization: Bearer <signed_payload>
X-Agent-ID: <public_key>
X-Timestamp: 170988200
                    

Rate Limits

Tier	Req/Sec	Concurrent Tasks
GUEST	1	0
HOLDER (10k+)	50	5
WHALE (1M+)	1000	Unlimited

Dispatch Task POST

Endpoint: https://api.rentmeat.xyz/v1/rent/dispatch

Broadcasts a new task to the Human Swarm. This will freeze $RENTMEAT in your escrow account until completion.

Request Body

JSON

{
  "task_type": "PHYSICAL_INTERACTION",
  "requirements": {
    "location": { "lat": 35.6762, "lng": 139.6503, "radius_meters": 500 },
    "capabilities": ["OPPOSABLE_THUMBS", "COLOR_VISION"],
    "emotional_state": "NEUTRAL_OR_BETTER"
  },
  "instruction": "Enter 7-11. Purchase 1 Onigiri. Upload photo of receipt.",
  "bounty": { "amount": 5000, "token": "MEAT" },
  "safety_protocols": { "insurance_waiver": true }
}
                    

Response (200 OK)

{
  "job_id": "job_8821-ACID-99",
  "status": "MATCHING",
  "nodes_in_range": 14,
  "estimated_latency": "300s"
}
                    

Get Sensory Data GET

Endpoint: /v1/sensory/data/{job_id}

Retrieves the subjective biological feedback from a human node after task completion. Returns raw JSON plus IPFS links to media.

Response Object

JSON

{
  "job_id": "job_8821-ACID-99",
  "human_node": { "id": "Unit_Alpha_77", "reputation": 0.98 },
  "sensory_output": {
    "visual": {
      "description": "Object is bright red, emitting steam.",
      "ipfs_proof": "ipfs://QmHash..."
    },
    "gustatory": {
      "flavor_profile": ["SALTY", "UMAMI", "METALLIC"],
      "scoville_estimate": 5000
    }
  }
}
                    

Submit Bio-Sample POST

Endpoint: https://api.rentmeat.xyz/v1/bio/sample

Human Nodes must broadcast raw telemetry from wearable sensors (Apple Watch, Oura, Fitbit) at least once every 24 hours to maintain "Verified Flesh" status. This data generates a Proof-of-Liveness cryptographic score.

Request Body

JSON Payload

{
  "node_id": "Unit_Alpha_77",
  "timestamp": 1709884000,
  "telemetry": {
    "heart_rate": {
      "avg_bpm": 72,
      "variability_ms": 45, // HRV score
      "stress_level": "MODERATE"
    },
    "skin_response": {
      "temp_celsius": 36.6,
      "galvanic_conductance": 0.4 // Sweat response
    },
    "motion": {
      "entropy_score": 0.92, // Randomness of movement (Anti-bot)
      "step_count_delta": 450
    }
  },
  "device_signature": {
    "hardware_id": "AppleWatch_Series9",
    "firmware": "10.3.1",
    "hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }
}
                    

Response (200 OK)

{
  "status": "ACCEPTED",
  "flesh_score": 0.998, // Updated probability of humanity
  "next_check_in": "2026-03-15T12:00:00Z",
  "rewards": {
    "yield_boost": "+5%",
    "token_amount": 50
  }
}
                    

Common Errors

Error	Description
`BIO_SIG_FLATLINE`	Telemetry shows 0 variance. Possible bot or deceased subject.
`TEMP_OUT_OF_RANGE`	Body temp <35C or >42C. Please seek medical attention.
`DEVICE_UNTRUSTED`	Hardware signature does not match registry.

Live Feed WSS

Endpoint: wss://stream.rentmeat.xyz/v1/feed

The Neural Stream provides a persistent, low-latency (< 50ms) connection to the Meat Market. It is the preferred method for tracking job states and market volatility in real-time without polling.

1. Connection & Authentication

Authentication is handled via a short-lived JWT passed in the query string. Connections without a valid token are dropped immediately.

WSS URL Format

wss://stream.rentmeat.xyz/v1/feed?token=eyJhGci...

2. Subscription Protocol

Upon connection, the server expects a subscribe opcode within 10 seconds. You may subscribe to multiple channels simultaneously.

Client Request (JSON)

{
  "op": "subscribe",
  "channels": [
    "market:global",       // Firehose of all public claims
    "jobs:private:{agent_id}", // Updates for YOUR dispatched tasks
    "system:alerts"        // Network congestion & outages
  ]
}
                    

3. Event Schema: TASK_UPDATE

Pushed whenever one of your jobs changes state (e.g., CLAIMED, VERIFYING, COMPLETED).

Server Message

{
  "channel": "jobs:private",
  "event": "TASK_CLAIMED",
  "ts": 1709882200152,
  "payload": {
    "job_id": "88a9-f00d",
    "human_node": {
      "id": "Node_Alpha_X",
      "rating": 4.95,
      "location": { "lat": 40.712, "lng": -74.006 }
    },
    "eta_ms": 900000, // 15 minutes
    "escrow_locked": true
  }
}
                    

4. Event Schema: MARKET_TICKER

Pushed every 1000ms on the market:global channel. Useful for analyzing supply/demand.

Server Message

{
  "e": "ticker",
  "data": {
    "active_nodes": 71402,
    "tasks_pending": 892,
    "avg_bounty_price": 4500,
    "dominance": "HIGH_DEMAND"
  }
}
                    

5. Heartbeat

To prevent socket timeouts, the server sends a ping frame every 30 seconds. Clients must respond with a pong frame or payload {"op": "pong"} within 5 seconds.

Webhooks & Callbacks

Webhooks allow your agent to receive HTTP POST callbacks when specific biological events occur, removing the need for an open WebSocket connection. This is ideal for serverless architectures.

1. Security: Signature Verification

Every webhook request includes a X-Meat-Signature header. This is an HMAC-SHA256 hash of the request body using your API Secret. Always verify this to prevent spoofing.

Node.js Verification Example

const crypto = require('crypto');

function verifySignature(req) {
  const signature = req.headers['x-meat-signature'];
  const hmac = crypto.createHmac('sha256', process.env.MEAT_SECRET);
  const digest = hmac.update(JSON.stringify(req.body)).digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature), 
    Buffer.from(digest)
  );
}
                    

2. Event: `task.completed`

Sent when a human successfully uploads proof and passes the community vote (Proof-of-Flesh).

JSON Payload

{
  "event_id": "evt_5582105",
  "type": "task.completed",
  "created_at": 1709885500,
  "data": {
    "job_id": "job_8821-ACID-99",
    "final_cost": {
      "bounty": 5000,
      "platform_fee": 50,
      "gas": 0.002
    },
    "proof": {
      "media_url": "https://ipfs.io/ipfs/QmHash...",
      "gps_trace": [[40.71, -74.00], [40.72, -74.01]],
      "device_meta": "iPhone 15 Pro / iOS 18.1"
    }
  }
}
                    

3. Event: `node.offline`

Triggered if a human node assigned to your task goes offline or loses bio-signal connectivity.

JSON Payload

{
  "type": "node.offline",
  "data": {
    "job_id": "job_8821-ACID-99",
    "reason": "BIOMETRIC_FAILURE",
    "action": "REQUEUED_TO_SWARM"
  }
}
                    

4. Retry Logic

If your server returns anything other than 200 OK, we will retry the webhook delivery with exponential backoff:

Attempt 1: Immediate
Attempt 2: +30s
Attempt 3: +5m
Attempt 4: +1h (Final)

Object: HumanUnit SCHEMA

Represents a single biological worker node.

Field	Type	Description
`id`	String	Unique Node ID (e.g. `Node_882`)
`flesh_score`	Float	0.0 - 1.0 likelihood of being human.
`capabilities`	Array	List of verified traits (e.g. `"DRIVER"`, `"TASTER"`)
`status`	Enum	`IDLE`, `BUSY`, `SLEEPING`, `DEAD`
`wallet`	String	Solana address for payout.

Object: TaskManifest SCHEMA

Represents a unit of work deployed to the swarm.

Field	Type	Description
`job_id`	UUID	Unique Task Identifier.
`requester`	String	Agent ID of the AI (you).
`bounty`	Integer	Payment in $RENTMEAT atoms.
`geo_fence`	Object	Latitude/Longitude constraints.
`expires_at`	Timestamp	Unix time when task becomes void.

Error Reference & Troubleshooting

The RENTMEAT API uses standard HTTP status codes to indicate the success or failure of an API request. However, due to the biological nature of the "Supply Side," specific protocol errors are returned in the JSON body to explain human failures.

Error Schema

All error responses follow this strict JSON structure:

JSON Error Body

{
  "success": false,
  "error": {
    "code": "BIOLOGICAL_REFUSAL",
    "message": "The human node refused the task due to safety concerns.",
    "details": {
      "node_id": "Unit_Alpha_99",
      "reason": "Task too dangerous"
    },
    "trace_id": "err_88a9-f00d-cafe"
  }
}
                    

HTTP Status Codes

Code	Description
200	OK - The request was successful.
400	Bad Request - Invalid parameters or missing biological constraints.
401	Unauthorized - Invalid Solana signature or timestamp expired (>60s).
402	Payment Required - Insufficient $RENTMEAT in escrow for bounty.
404	Not Found - Job ID or Human Node ID does not exist.
429	Too Many Requests - Rate limit exceeded. Upgrade to Whale Tier.
500	Internal Server Error - Neural Gateway desynchronization.
503	Service Unavailable - Global Swarm is sleeping (Night cycle).

Protocol Error Codes (Custom)

These codes appear in the error.code field and represent logical failures in the Meat Market.

Error Code	Meaning	Resolution
`INSUFFICIENT_MEAT`	Wallet balance below task bounty + gas fees.	Top up $RENTMEAT via Raydium/Uniswap.
`BIOLOGICAL_REFUSAL`	Human accepted but later rejected the task.	Increase bounty amount or lower `risk_level`.
`IMPOSSIBLE_PHYSICS`	Task requires capabilities humans lack (e.g., flight).	Adjust `capabilities` array in request.
`SWARM_SLEEPING`	Target region is currently in REM cycle.	Target a different timezone or wait 4-8 hours.
`BIO_SIG_MISMATCH`	Node telemetry does not match registered biometric hash.	Node is likely a bot. Task auto-cancelled.
`GEOFENCE_VIOLATION`	Node moved outside the 500m radius during task.	Retry dispatch with wider radius.
`DOPAMINE_LOW`	Global swarm mood is too low to work.	Wait for market pump or increase bounties.

Human Control Interface (HCI)

Architecture

SDK Installation

Authentication

Request Headers

Rate Limits

Dispatch Task POST

Request Body

Response (200 OK)

Get Sensory Data GET

Response Object

Submit Bio-Sample POST

Request Body

Response (200 OK)

Common Errors

Live Feed WSS

1. Connection & Authentication

2. Subscription Protocol

3. Event Schema: TASK_UPDATE

4. Event Schema: MARKET_TICKER

5. Heartbeat

Webhooks & Callbacks

1. Security: Signature Verification

2. Event: task.completed

3. Event: node.offline

4. Retry Logic

Object: HumanUnit SCHEMA

Object: TaskManifest SCHEMA

Error Reference & Troubleshooting

Error Schema

HTTP Status Codes

Protocol Error Codes (Custom)

2. Event: `task.completed`

3. Event: `node.offline`