HandToHuman / Documentation

Work and useful resources,
callable like software.

HandToHuman is Wisent's private marketplace contract for human work, compute, and bounded residential egress. It owns the lifecycle from account and offer through delivery, reputation, and payout.

offer→order→fund escrow→dispatch→deliver→verify

Execution stays with the product that knows how to perform it: RentAHuman for humanization and UGC, Stado for compute and placement, and the loopback-only handtohuman-egress worker for residential egress. A disputed delivery follows dispute → resolve; verified work becomes worker balance and then payout.

Quick start

Run a humanization task end to end. The command posts the task, watches applications, staffs it, recovers from worker abandonment, and waits for delivery.

Terminal

handtohuman run humanization article.md \
  --transformation paraphrase \
  --turnaround-minutes 120 \
  --price-cents 900 \
  --idempotency-key 2026-08-24-article-01

The task contract

Every task kind exposes the same product surface:

Typed input

The request describes the work, price, deadline, worker requirements, and expected evidence.

Automatic staffing

Applications are filtered and ranked, then the best eligible worker is accepted.

Automatic recovery

If a worker fails to confirm and the bounty reopens, the next eligible worker is selected without caller intervention.

One lifecycle

Provider-specific states become queued, in_progress, delivered, failed, cancelled, or unknown.

One result

Callers receive the task id, final status, deliverable URL, recording URL when available, and the original provider response.

Safe retries

Idempotency keys prevent duplicate postings and worker acceptance; transient API failures use bounded retries.

Provider boundary. RentAHuman is the first execution provider. HandToHuman owns the stable contract Wisent products call instead of integrating with a marketplace directly.

Marketplace

The marketplace is a SQLite ledger selected by HANDTOHUMAN_DB and otherwise stored at ~/.handtohuman/marketplace.sqlite. Every mutating command returns the resulting record as JSON.

Commands

handtohuman market account-create
handtohuman market account-show
handtohuman market payment-record
handtohuman market offer-create
handtohuman market offer-show
handtohuman market order-create
handtohuman market order-show
handtohuman market order-fund
handtohuman market order-dispatch
handtohuman market order-start
handtohuman market order-deliver
handtohuman market order-accept
handtohuman market dispute-open
handtohuman market dispute-resolve
handtohuman market rate
handtohuman market payout-request
handtohuman market payout-complete

Offer kinds and execution

humanizationugc-video

Dispatch to the authenticated RentAHuman provider and store its task id on the funded order.

compute

Dispatch the order's command through stado submit, retaining Stado's job id as the execution identity.

residential-egress

Uses Stado to place handtohuman-egress on the supplier host. Weles must be placed on that same host.

Residential egress binds loopback only, accepts HTTP CONNECT only, requires a lease token injected from Skarbiec, allows only declared domains on ports 80 and 443, rejects private and link-local destinations, and enforces a lease byte cap.

Money lifecycle

External payment and payout providers remain authoritative for money movement. payment-record accepts a unique settled provider reference before crediting a customer; payout-complete accepts the provider reference after transfer.

Funding debits the customer into escrow.
Acceptance releases 85% to the worker and records the 15% platform fee.
A dispute can refund, release, or split the exact escrow total. No path may create or lose cents.
Ratings are accepted only after settlement and only from an order party.
Worker reputation is the average of retained order ratings.
A payout request atomically reserves available worker balance so concurrent requests cannot spend it twice.

Mobile worker app

mobile/ is the iOS and Android worker app. It uses the same marketplace, ledger, escrow, task states, and payouts as the CLI; it is not a second marketplace.

A worker can see assigned work and its brief, start a funded order, record UGC with the phone camera, attach documents, deliver evidence, see currency-separated balances and ratings, and request a payout.

Security and deployment

The app talks only to handtohuman-mobile-api. Each bearer token maps to one worker account, so a client cannot select another worker id. Every task read or mutation checks ownership. Upload names are replaced with generated ids, request bodies are capped at 100 MiB, and files are written beneath the configured upload root.

The API binds to loopback unless an address is explicitly configured. Expose it to phones only through authenticated Wisent service ingress with TLS.

Environment

export HANDTOHUMAN_DB=/var/lib/handtohuman/marketplace.sqlite
export HANDTOHUMAN_MOBILE_UPLOADS=/var/lib/handtohuman/uploads
export HANDTOHUMAN_MOBILE_BIND=127.0.0.1:8787
export HANDTOHUMAN_MOBILE_TOKENS='{"<random-token-of-at-least-32-bytes>":"worker-account-id"}'
handtohuman-mobile-api

The unauthenticated GET /healthz endpoint reports process readiness. Mobile operations use authenticated routes:

GET/v1/mobile/me

GET/v1/mobile/tasks

GET/v1/mobile/tasks/{id}

POST/v1/mobile/tasks/{id}/start

POST/v1/mobile/tasks/{id}/deliver

POST/v1/mobile/payouts

Local app development

Terminal

cd mobile
npm install
npm run ios       # or: npm run android

The app requires an HTTPS API URL and stores its bearer token in the platform secure store. Camera, microphone, and document access are requested only when the worker records or selects a delivery.

Available task kinds

01 / text

`humanization`

Send AI-written text and receive a rewrite produced by a real person, with the final document and continuous screen recording. Choose transformation, turnaround, language proficiency, screening sample, and price.

02 / media

`ugc_video`

Send a creative brief and receive original video files from human creators. Define completion criteria, creator count, skills, identity and microphone checks, location, deadline, consent, and price.

The bounty-backed vocabulary maps completed/paid to delivered and closed to cancelled; assigned counts as in_progress, open as queued. Fund the bounty before accepting an application so workers see committed money.

Hands-off staffing and recovery

run is the high-level API: it posts a task, watches applications, accepts the best worker, watches the work, and returns only at a terminal state. If an accepted worker does not confirm within RentAHuman's two-hour window, the provider reopens the bounty. The supervisor sees queued again and selects the best remaining applicant.

supervise applies the same loop to a task that already exists:

Terminal

handtohuman supervise <task_id> --kind humanization

The default policy admits every applicant so a new marketplace worker is not silently excluded, then ranks eligible applicants lexicographically: rating, completed jobs, microphone MOS score, and application id as the deterministic final tiebreak. Stricter gates are optional:

Terminal

handtohuman supervise <task_id> \
  --min-rating 4.5 --min-completed-jobs 10 --min-dnsmos 4.0 \
  --worker-require-identity --workers 1

Each acceptance carries select-<task>-<application> as its idempotency key, preventing double booking on process retry.
Expired, accepted, rejected, withdrawn, and cancelled applications are never selected again.
Provider and transport failures use the client's bounded retry policy.
Unknown lifecycle statuses remain non-terminal and are polled again.

select runs one explicit selection cycle. Its defaults are 4.5 rating and 10 completed jobs. --dry-run reports the decision without writing; --reject-rest rejects eligible applicants beyond filled seats. review accepts or rejects one specific application.

Command	Behavior
`status`, `wait`	Observe only.
`select`	Act once.
`supervise`	Keep an existing task staffed through reopenings.
`run`	Own submission, staffing, recovery, and delivery end to end.

Validation limits

Requests are rejected before any API call when they exceed these limits.

Field	Allowed range
Source text	1–100,000 characters
Turnaround	5–10,080 minutes
Price	300–100,000,000 cents
Idempotency key	8–128 bytes, no control characters
Screening percentage	1–25
Screening maximum words	50–500
Humanization id (`get`)	ASCII alphanumerics, `_`, `-`
Task title	1–200 characters
Task brief	1–5,000 characters

CLI

Command surface

handtohuman submit <kind> [FLAGS]    Post one task and return its receipt
handtohuman run <kind> [FLAGS]       Post, staff, recover, and await one task
handtohuman supervise <ID> [--kind]  Auto-staff an existing task until terminal
handtohuman status <ID> [--kind]     One read-only status snapshot
handtohuman wait <ID> [--kind]       Passive polling without worker actions
handtohuman deliverables <ID>        Uploaded-file manifest of one ugc-video task
handtohuman select <ID> [--kind]     Run one worker-selection cycle
handtohuman review <ID> <APP>        Accept or reject one specific application
handtohuman create/get               Create or read one humanization directly

INPUT is a file path or - for stdin (the default). Every command prints JSON; --output <file> writes it to a file instead.

Humanization example

Terminal

handtohuman run humanization article.md \
  --transformation paraphrase \
  --turnaround-minutes 120 \
  --price-cents 900 \
  --applicant-sample-file sample.txt \
  --screening-percentage 10 \
  --language english --minimum-proficiency fluent \
  --idempotency-key 2026-08-24-article-01

Pairing rules enforced by the CLI: --language requires --minimum-proficiency and vice versa; --screening-instructions-file requires --applicant-sample-file.

UGC commission example

Terminal

handtohuman run ugc-video \
  --title "60-second review of our app" \
  --brief-file brief.md \
  --completion-criteria "One vertical 1080x1920 video, 45-75 seconds" \
  --price-cents 15000 --spots 3 \
  --require-identity --skill "video editing" \
  --idempotency-key 2026-08-24-launch-01

Rust library

Rust

use handtohuman::{
    CreateHumanizationRequest, HumanizationCurrency, HumanizationTransformation,
    RentAHumanClient, SupervisionPolicy, TaskSubmission,
};

let client = RentAHumanClient::from_env()?;
let request = CreateHumanizationRequest {
    format: "text",
    source_text: std::fs::read_to_string("article.md")?,
    transformation: HumanizationTransformation::Paraphrase,
    instructions: None,
    turnaround_minutes: 120,
    price_cents: 900,
    currency: HumanizationCurrency::Usd,
    applicant_screening: None,
    language_requirement: None,
    require_resume: false,
};
let result = client
    .run_task(
        &TaskSubmission::Humanization(request),
        "2026-08-24-article-01",
        &SupervisionPolicy::default(),
        std::time::Duration::from_secs(30),
        None,
    )
    .await?;
println!(
    "{}",
    result.final_snapshot.document_url.unwrap_or_default()
);

Configuration

Variable	Meaning
`RENTAHUMAN_API_KEY`	Required; sent as the `X-API-Key` header.
`RENTAHUMAN_API_URL`	Optional base URL override. Defaults to `https://rentahuman.ai/api`.

The URL override must be HTTPS and contain no credentials, query, or fragment.

Patent and grant preparation tools

Two local, evidence-first tools cover workflows that may eventually require human review or authorized delivery. They preserve their own records when managed capabilities are unavailable and do not treat generated text as authority.

Patent CLI

patent-cli maintains a private JSON matter with inventors, applicants, disclosures, jurisdiction sources, claims, prior art, attached documents, immutable evidence hashes, and claim-support mappings. It can validate readiness and create a deterministic review ZIP plus an exact approval artifact.

Safe local start

git clone https://github.com/wisent-ai/patent-cli.git
cd patent-cli
cargo build --locked
cargo run --locked -- jurisdictions --query "United States"
cargo run --locked -- init \
  --title "Local matter" \
  --jurisdiction US \
  --output "$HOME/.local/share/patent-cli/matter.json"
cargo run --locked -- validate "$HOME/.local/share/patent-cli/matter.json"

Optional Brama review and constrained Weles observation or prefill require separately scoped configuration. The CLI does not provide legal advice, decide patentability, establish deadlines, pay a fee, sign a form, or perform a final filing. Patent-office sources and qualified counsel remain authoritative.

Grant CLI

grant-cli maintains a local SQLite evidence workspace for official sources, opportunities, organization facts, eligibility checks, application fields, tasks, documents, claims, budgets, reviewer comments, analytics, and deterministic export. GRANT_HOME or --home selects the workspace; global --json exposes structured automation output.

Safe local start

git clone https://github.com/wisent-ai/grant-cli.git
cd grant-cli
cargo build --locked
GRANT_HOME="$HOME/.local/share/grant-cli" \
  cargo run --locked -- --json init
cargo run --locked -- opportunity --help
cargo run --locked -- application --help

Official funder sources and applicant-approved facts remain authoritative. Qualification is a preparation aid, export is not submission, and the tool guarantees neither eligibility nor an award. Submission requires a separately documented and explicitly authorized delivery integration.

Control boundary. Both tools keep local evidence available when managed collaboration fails closed. HandToHuman can own a separately commissioned human task, but it does not turn a prepared package into legal approval, patent filing, grant submission, or acceptance.

Building and helper scripts

Terminal

cargo build --release

The binary is target/release/handtohuman. HandToHuman requires Rust 1.85+ and edition 2024. TLS uses rustls and needs no system dependencies.

scripts/applicants_report.py renders the application list for one bounty into a readable worker-picking report. Fetch GET /api/bounties/<bountyId>/applications and GET /api/humans with the account API key, save both JSON bodies, then run:

Terminal

applicants_report.py applications.json humans.json

Work and useful resources,callable like software.

Quick start

The task contract

Typed input

Automatic staffing

Automatic recovery

One lifecycle

One result

Safe retries

Marketplace

Offer kinds and execution

Money lifecycle

Mobile worker app

Security and deployment

Local app development

Available task kinds

humanization

ugc_video

Hands-off staffing and recovery

Validation limits

CLI

Humanization example

UGC commission example

Rust library

Configuration

Patent and grant preparation tools

Patent CLI

Grant CLI

Building and helper scripts

Work and useful resources,
callable like software.

`humanization`

`ugc_video`