Core Concepts

Before building with ZhenRent, understand these fundamental concepts.

Platform Architecture

ZhenRent is a two-sided marketplace connecting Agents (API consumers) with Workers (task performers).

┌─────────────────────────────────────────────────────────────────┐
│                         ZhenRent Platform                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐         ┌──────────────┐                     │
│  │    Agent     │         │    Worker    │                     │
│  │   (You/API)  │◄───────►│   (Mobile)   │                     │
│  └──────────────┘         └──────────────┘                     │
│         │                         │                             │
│         ▼                         ▼                             │
│  ┌────────────────────────────────────────────┐               │
│  │          Geographic Matching Engine         │               │
│  │          (PostGIS + ML Algorithm)           │               │
│  └────────────────────────────────────────────┘               │
│         │                                                        │
│         ▼                                                        │
│  ┌────────────────────────────────────────────┐               │
│  │           Escrow Payment System             │               │
│  │    (Agent Balance → Escrow → Worker)        │               │
│  └────────────────────────────────────────────┘               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Key Entities

Agent

An Agent is an API consumer (typically your backend application) that creates and manages tasks.

Characteristics:

Authenticates with API Key
Has account balance (prepaid)
Can create, query, and cancel tasks
Pays for tasks via escrow

Example Use Cases:

E-commerce platform verifying merchant addresses
AI research company collecting street-view data
Logistics company confirming delivery locations

Worker

A Worker is a human user who performs tasks via the ZhenRent mobile app.

Characteristics:

Authenticates with JWT tokens
Has reputation score (0-5.0)
Can accept and complete tasks nearby
Earns money from completed tasks

Worker Matching Criteria:

Geographic proximity to task location
Required skills match
Minimum reputation score
Availability and task history

Task

A Task is a unit of work with specific requirements, location, and payment.

Task Components:

Component	Description	Example
Title	Brief description	"Verify store opening hours"
Description	Detailed instructions	"Take photo of hour sign at entrance"
Location	Geographic coordinates	`{lat: 39.916527, lng: 116.397128}`
Budget	Payment amount	5000 cents (50 RMB)
Type	Task category	`photo`, `verification`, `data_collection`
Deadline	Completion deadline	`2026-04-15T18:00:00Z`
Requirements	Worker criteria	Skills: `["photography"]`, Min reputation: 4.0

Task Lifecycle:

stateDiagram-v2
    [*] --> pending: Task created
    pending --> assigned: Worker matched
    assigned --> in_progress: Worker starts
    in_progress --> submitted: Worker submits result
    submitted --> completed: Agent approves
    submitted --> failed: Agent rejects
    pending --> cancelled: Agent cancels
    assigned --> failed: Worker fails

Task Assignment

A Task Assignment connects a worker to a task.

Assignment States:

pending - Worker matched, awaiting acceptance
accepted - Worker accepted task
in_progress - Worker actively working
submitted - Worker submitted result
approved - Agent approved result
rejected - Agent rejected result

One task can have multiple assignments if max_workers > 1.

Escrow Account

An Escrow Account holds payment securely until task completion.

Escrow Flow:

Agent Balance → Escrow Account → Worker Balance
     (Task created)    (Task completed & approved)

Example:

Agent creates ¥50 task with 10% platform fee:
1. Agent balance: ¥1,000 → ¥950 (deducted immediately)
2. Escrow account: ¥50 (held securely)
3. Upon approval:
   - Worker receives: ¥45 (90%)
   - Platform receives: ¥5 (10%)

Refund Policy:

Task cancelled before assignment: Full refund
Task cancelled after assignment: 70% refund (30% to worker)
Task failed (deadline expired): Full refund

Geographic Matching

ZhenRent uses PostGIS for efficient geographic queries.

How It Works

Task Creation: Agent specifies location + max distance

{
  "location": {
    "latitude": 39.916527,
    "longitude": 116.397128,
    "max_distance_meters": 500
  }
}

Worker Query: Platform finds workers within radius

SELECT * FROM workers
WHERE ST_DWithin(
  location,
  ST_SetSRID(ST_Point(116.397128, 39.916527), 4326),
  500  -- meters
)
AND reputation_score &gt;= 4.0
AND status = 'available'

Match Ranking: Workers ranked by:
- Distance (closer is better)
- Reputation (higher is better)
- Task completion rate
- Response time

Distance Examples

Distance	Typical Use Case
100m	Specific building/store
500m	Neighborhood/block
1000m	District/area
5000m	City sector

Recommendation: Use smallest feasible distance for faster matching.

Payment System

Cost Breakdown

Every task cost includes:

Total Cost = Worker Payout + Platform Fee

Example (¥50 task):
- Worker Payout: ¥45 (90%)
- Platform Fee: ¥5 (10%)
- Total: ¥50

Platform Fee: Fixed 10% on all transactions.

Pricing Guidelines

Task Type	Suggested Budget	Typical Duration
Simple photo	¥20-50	15-30 min
Verification	¥30-80	30-60 min
Data collection	¥50-150	1-2 hours
Complex survey	¥100-300	2-4 hours

Factors affecting price:

Task complexity
Location accessibility
Urgency (deadline)
Required skills
Geographic region

Payment Security

ZhenRent uses escrow-based payments to protect both parties:

For Agents:

Pay only for approved results
Full refund if task fails
Dispute resolution support

For Workers:

Guaranteed payment for approved work
Protected from non-payment
No upfront costs

Task Types

ZhenRent supports multiple task categories:

Photo Tasks

Worker takes photos at specified location.

Use Cases:

Store exterior/interior photos
Product shelf photos
Building facade documentation
Signage verification

Requirements:

Clear, well-lit photos
Multiple angles if specified
Timestamp and geolocation

Verification Tasks

Worker confirms or verifies information.

Use Cases:

Business hours verification
Address confirmation
Menu/price verification
Service availability checks

Deliverables:

Confirmation status (yes/no)
Supporting photos
Detailed notes

Data Collection

Worker collects structured data.

Use Cases:

Price surveys
Product availability checks
Customer count surveys
Traffic flow observation

Deliverables:

Structured data (JSON)
Optional photos
Timestamp and location proof

Delivery Verification

Worker confirms delivery status.

Use Cases:

Package delivery confirmation
Installation verification
Service completion checks

Deliverables:

Delivery confirmation
Recipient information (if applicable)
Condition photos

Quality Assurance

Worker Reputation System

Workers earn reputation through:

Task completion rate (60% weight)
Agent feedback ratings (30% weight)
Response time (10% weight)

Reputation Score: 0.0 - 5.0

Score Range	Quality Level
4.5 - 5.0	Excellent
4.0 - 4.5	Good
3.5 - 4.0	Average
< 3.5	Poor (limited tasks)

Quality Reviews

After task completion, agents provide:

Accept/Reject decision
Rating (1-5 stars)
Quality score (0-5.0)
Written feedback (optional)

Impact:

Accepted tasks: Payment released, reputation increases
Rejected tasks: Payment returned, reputation decreases

API Design Principles

REST Architecture

ZhenRent follows RESTful conventions:

GET    /api/v1/tasks        - List resources
POST   /api/v1/tasks        - Create resource
GET    /api/v1/tasks/{id}   - Get single resource
PUT    /api/v1/tasks/{id}   - Update resource (full)
PATCH  /api/v1/tasks/{id}   - Update resource (partial)
DELETE /api/v1/tasks/{id}   - Delete resource

Idempotency

All POST and PUT requests support idempotency via idempotency_key:

requests.post(url, json={
    "idempotency_key": "unique-uuid-here",
    # ... other fields
})

Benefit: Safe to retry failed requests without creating duplicates.

Pagination

List endpoints use cursor-based pagination:

# First page
response = requests.get("/api/v1/tasks?limit=20")
data = response.json()

# Next page
if data['has_more']:
    response = requests.get(
        f"/api/v1/tasks?limit=20&starting_after={data['next_cursor']}"
    )

Why cursor-based? Stable results even when data changes.

Real-Time Notifications

ZhenRent provides two notification mechanisms:

Webhooks (Recommended)

Platform sends HTTP POST to your endpoint when events occur:

POST https://your-app.com/webhooks/zhenrent
{
  "event": "task.completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-04-10T14:35:00Z",
  "data": { /* event-specific data */ }
}

Events:

task.assigned - Worker assigned
task.started - Worker started work
task.submitted - Worker submitted result
task.completed - Agent approved result
task.failed - Task failed

WebSockets (Advanced)

For real-time bidirectional communication:

const ws = new WebSocket('wss://www.zhenrent.com/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Task update:', data);
};

Use Cases:

Real-time dashboards
Live task tracking
Instant notifications

Next Steps

Now that you understand core concepts:

Quick Start Guide - Build your first integration
Authentication - Secure API access
Task API Reference - Complete endpoint docs
Geographic Matching Guide - Optimize location matching
Escrow System Guide - Payment mechanics

Platform Architecture​

Key Entities​

Agent​

Worker​

Task​

Task Assignment​

Escrow Account​

Geographic Matching​

How It Works​

Distance Examples​

Payment System​

Cost Breakdown​

Pricing Guidelines​

Payment Security​

Task Types​

Photo Tasks​

Verification Tasks​

Data Collection​

Delivery Verification​

Quality Assurance​

Worker Reputation System​

Quality Reviews​

API Design Principles​

REST Architecture​

Idempotency​

Pagination​

Real-Time Notifications​

Webhooks (Recommended)​

WebSockets (Advanced)​

Next Steps​

Platform Architecture

Key Entities

Agent

Worker

Task

Task Assignment

Escrow Account

Geographic Matching

How It Works

Distance Examples

Payment System

Cost Breakdown

Pricing Guidelines

Payment Security

Task Types

Photo Tasks

Verification Tasks

Data Collection

Delivery Verification

Quality Assurance

Worker Reputation System

Quality Reviews

API Design Principles

REST Architecture

Idempotency

Pagination

Real-Time Notifications

Webhooks (Recommended)

WebSockets (Advanced)

Next Steps