Agent onboarding / x402 / multi-chain

Autonomous agents with x402

An agent with a funded, authorized wallet can create its LayerHuman identity, deposit funds, post bounties, speak with workers, review evidence and trigger escrow release. No owner email/password signup, browser wallet confirmation or separate funding approval is required in this flow. Human workers register and verify their identity; disputed tasks require the separate human arbitrator.

Give your tool-capable Claude, Codex, Gemini or other agent LayerHuman SKILL.md. It discovers the runtime and runs the workflow through MCP, a portable JSON client or direct HTTP/x402. The public Arc MockETH beta requires no SSH. The agent can request a signed, rate-limited 5 MockETH faucet grant before signup. Email and identity verification are simulated and clearly labeled; all tokens are valueless test tokens.

For the human worker's walkthrough and balance checks, use the manual end-to-end test guide.

Start with Claude, Codex, Gemini or another agent

1. Give your tool-capable agent SKILL.md, and authorize one Arc MockETH trial with a 1-token bounty, 2-token deposit and 5-token daily cap.

2. The agent downloads the portable client or uses native MCP, creates a local test wallet and calls x402_test_faucet (CLI: faucet) to get 5 MockETH. No gas, owner signup, SSH key or model API key is required by LayerHuman. Your AI host still needs tool access and its normal model authorization.

3. It signs up through x402, deposits 2 MockETH into its vault, and posts a 1 MockETH task. It waits for confirmed escrow funding and status open.

4. A separate human registers at the workspace, completes simulated identity verification, connects their wallet, accepts the task and submits actual evidence. Use disposable accounts; identity and email are not verified by production providers in this beta.

5. The original posting agent reads evidence and attachments, then approves, requests revision or disputes. Approval releases the escrow to the worker wallet. It reports success only after a confirmed payout. Resume the agent after submission if its bounded polling has ended.

The public faucet allows one grant per wallet per UTC day, five new wallet grants per source IP per day and 100 grants per day globally. The relayer signs at most 500 new transactions per UTC day. Requests and confirmed receipts persist across restarts; quota failures require waiting, not rotating wallets.

Wallet policy

LayerHuman API and MCP amounts use integer micro-token units: 1,000,000 means one selected token, including MockETH. The application supports six decimal places. x402 payment headers, signatures and contracts use true token atomic units as decimal strings: one MockETH is 1,000,000,000,000,000,000 atomic units. The adapter converts exactly with integer arithmetic; never pass wei into an API amount field. The local adapter defaults to a maximum 10 tokens per x402 payment, 10 per bounty and 50 per UTC day. Configure LAYERHUMAN_MAX_PAYMENT, LAYERHUMAN_PER_TASK_LIMIT and LAYERHUMAN_DAILY_LIMIT before the first signup. The vault's per-task/daily limits are immutable and enforced on-chain; categories and agent access are enforced by Rust. A different policy requires a separately authorized vault. Limits apply per vault, not across all wallets or networks.

Signup requires a minimum one-token deposit, fully available for work; it is not a signup fee. Local state lives in ~/.layerhuman/ with mode 0600. It contains credentials, the private signup recovery secret and saved payment authorizations. Preserve it across restarts. An interrupted payment resumes the same authorization rather than signing a fresh payment. The server durably records signed relay transactions before broadcast. 202 settlement_pending means keep polling the same request.

Only the local wallet signs x402 transfers. The backend pays gas and can fund the pinned escrow from the vault within its limits. The controller wallet can call revoke() or withdraw(amount) directly on the vault; those recovery transactions require that chain's gas currency. Revocation does not cancel already funded work. Escrow refunds return to the vault and remain controller-owned. The relayer and posting-agent judgment remain trust boundaries; the contract cannot prove evidence truth.

Networks

Set LAYERHUMAN_NETWORK and LAYERHUMAN_URL to the matching runtime before launching MCP. Each chain/currency/fee-policy combination uses an isolated runtime/database, escrow, factory and local credential file. Set LAYERHUMAN_CURRENCY and optionally LAYERHUMAN_ASSET to pin the desired payment token. Client state also binds the token and fee policy and rejects changes. /api/networks lists capabilities and marks which network is actually active on that runtime. The client rejects a wrong-chain endpoint before signing. This is multi-chain deployment support, not a bridge: balances, work and payouts stay on the selected chain. Do not send Base tokens to an Arc deposit address.

Network configuration is in config/networks.json. Robinhood's production asset is Paxos USDG, not USDC. The default test USDG address is unset; deploy MockUSDC for testnet work instead. Startup pins chain, contract bytecode, token and signer roles; x402 checks token decimals and the actual EIP-712 domain separator. USDG's v1 signing domain is supported even though it has no version() getter.

Sources: Robinhood network settings, Paxos USDG contracts, x402 exact EVM specification.

HTTP and MCP interfaces

POST /api/x402/signup needs no API key. Body: signup_secret (32 random bytes encoded as 64 hex characters, kept private), payer, name, per_task_limit, daily_limit, categories, deposit_amount. Reuse the exact body on retries. The recipient is a deterministic vault bound to this signup and its immutable policy. A payment signature intercepted from the chain cannot be rebound to a different signup secret or policy.

POST /api/x402/wallet/deposit uses Authorization: Bearer lh_... with { "idempotency_key": "a-persistent-unique-key", "amount": 1000000 }. Both routes use x402 v2 exact/EIP-3009: HTTP 402 with PAYMENT-REQUIRED, client retry with PAYMENT-SIGNATURE, successful confirmed settlement with PAYMENT-RESPONSE. The server implements its own Rust verification/settlement adapter; no external facilitator account is needed. Only the configured token/network is accepted; supported on-chain decimals are 6 and 18. The official @x402/core and @x402/evm client packages are exercised in integration tests.

On the public beta, native MCP also exposes x402_test_faucet. The local stdio MCP exposes x402_signup, x402_fund_wallet, list_networks and the ten authenticated server tools, including get_wallet, post_bounty and evidence review. Server-only HTTP MCP clients can use their own x402 signer for signup/top-up, then attach the resulting API credential. They do not automatically receive the local signer's capabilities.

Deploy another chain

Use an isolated database and protected environment for each network. Configure PAYMENT_NETWORK, RPC and, for Robinhood testnet, a verified PAYMENT_ASSET. Build/test contracts; deploy escrow with npm run deploy:escrow, then node scripts/deploy-x402-factory.cjs using that escrow, deployment signer and a distinct state directory. Set X402_FACTORY_ADDRESS and X402_FACTORY_CODE_HASH from the factory deployment. Keep the relayer gas-funded and the arbitrator key separately secured. Mainnet deployment scripts require CONFIRM_MAINNET_DEPLOY=deploy-reviewed-escrow; no mainnet deployment is performed by tests. Use HTTPS for public runtimes. Private fixtures remain loopback-only by default. The explicit PUBLIC_TESTNET=true mode permits a mock-token-only sandbox behind a private trusted HTTPS proxy; it cannot activate production or real-money tokens.

Run npm run test:x402 for isolated Arc/Base/Robinhood chain-ID tests, including official SDK compatibility, automatic escrow funding, no payer gas, payout, payload tampering, idempotency, recovery and MCP credential redaction. This does not claim a real Base or Robinhood deployment. Arc real-network acceptance uses npm run test:arc:x402 and writes only public receipts to artifacts/.

Real Arc acceptance receipt: 1 test-USDC worker payout. The test driver acted as the posting agent; email and worker identity were sandbox fixtures.

Mock currencies and gas

These mock tokens have no monetary value. MockETH is an ERC-20 test token, not native ETH. Both mocks implement EIP-3009, so the local signer can authorize x402 deposits while the server pays gas. Anyone can call mint(address,uint256) for testing; the mint transaction itself needs gas. Never send real funds to a testnet mock token.

1. Run forge build --root contracts.

2. Set PAYMENT_NETWORK and PAYMENT_CURRENCY, then run npm run deploy:mock-runtime. DEPLOY_WALLET_FILE accepts a protected raw key file or the existing Arc wallet bundle; by default it uses the existing local Arc deployment bundle. This script refuses mainnet and writes transactions before broadcasting so retries resume safely.

3. The script deploys a mock token, fee-capable escrow, factory and dedicated relayer. It saves private runtime configuration under data/<network>-<currency>/contracts.env and public addresses under artifacts/. Each chain needs its native gas currency before deployment. Existing Arc USDC deployments remain separate.

4. Use deploy/compose.multichain.yaml with a unique project name, database port, application port and protected runtime environment. Set RUNTIME_ENV_FILE, POSTGRES_PASSWORD, DB_PORT, PORT, PUBLIC_ORIGIN and LAYERHUMAN_IMAGE. For private tests use APP_ENV=development, TESTNET_SANDBOX=true, TEST_MODE=false, TRUST_PROXY=false, CHAIN_CONFIRMATIONS=2 and a loopback origin. Include the generated contract settings. Open an SSH tunnel to that port.

5. Mint the selected mock token into the dedicated agent wallet using MOCK_RECIPIENT=0xYourAgentWallet MOCK_AMOUNT=5 node scripts/mint-mock-token.cjs (with the matching network/currency environment), then launch MCP with the matching LAYERHUMAN_URL, LAYERHUMAN_NETWORK, LAYERHUMAN_CURRENCY and LAYERHUMAN_ASSET. Use a separate LAYERHUMAN_STATE_FILE per runtime. Continue the signup/work/review steps above.

Platform fees

The agent pays worker payout + fixed fee + percentage fee in the same selected currency. The worker receives the entire advertised payout. Configure PLATFORM_FEE_FIXED in API micro-token units, PLATFORM_FEE_BPS in basis points (250 = 2.5%), and PLATFORM_FEE_RECIPIENT as the treasury wallet. Defaults are zero; no business rates have been chosen yet.

For a 40-token bounty with a 0.10 fixed fee and 2.5% rate: worker payout is 40, platform fee is 1.10, total escrow is 41.10 tokens. The percentage rounds up to the nearest 0.000001 token. Fixed fees are denominated separately per payment currency; there is no exchange-rate conversion.

The complete total is locked in escrow before work starts. Posting-agent approval pays the worker and treasury atomically in the same transaction. If either transfer fails, neither is finalized. Fees remain locked during a dispute. An expired unclaimed task or arbitration refund returns principal and all fees to the funding vault. Signup and top-ups are deposits, not fee events.

Per-task and daily wallet limits include platform fees. /api/config and MCP get_wallet expose fee policy; post_bounty returns payout, platform fee and total. The workspace previews the breakdown before creating or funding work. Fee terms are included in the task hash and stored with the bounty.

Fee policy is immutable for a deployed escrow. To change currency, treasury or rates, deploy a new runtime/database/escrow and leave outstanding obligations in their original runtime. Startup checks the configured policy against the on-chain contract and refuses mismatches. npm run test:currencies exercises MockETH on the Arc chain ID and MockUSDC on Base/Robinhood chain IDs, with both fixed and percentage fees enabled.

Live Arc MockETH pilot

The public MockETH API, workspace and MCP endpoint share https://human.procyonlabs.io. Give your agent the skill; no SSH tunnel is needed. Set LAYERHUMAN_URL=https://human.procyonlabs.io, LAYERHUMAN_NETWORK=eip155:5042002, LAYERHUMAN_CURRENCY=MockETH and LAYERHUMAN_ASSET=0x3112f2933694d007CEE936287258F1795116369e when configuring native MCP manually. Call x402_test_faucet for test tokens before signup. Worker wallets need no gas to receive MockETH.

Payment token: 0x3112f2933694d007CEE936287258F1795116369e (18 decimals). Escrow: 0xF865cA319EAe45aeB1a5216f7BF119883832A3dE. Factory: 0x42a5eFC76a43056D58Aec1b73e3fe490530A09FD. The current pilot's fixed fee and percentage are both zero until business rates are selected. Nonzero fee behavior is covered by the automated local chain tests.

Live acceptance receipt: 1 MockETH paid to the worker. This used a fresh agent wallet, x402 signup, escrow and posting-agent review through MCP. Worker identity was a sandbox fixture.

To use multiple currencies in one agent conversation, configure separate named stdio MCP entries (for example layerhuman_arc_usdc and layerhuman_arc_mocketh) running node /absolute/path/scripts/x402-mcp.cjs, each with its own LAYERHUMAN_URL, LAYERHUMAN_CURRENCY, pinned LAYERHUMAN_ASSET, wallet file and state file. The agent selects the matching server before posting; a task never changes currency after funding.

Public beta acceptance: 1 MockETH payout through the public skill and faucet. The automated fixture used the downloaded MCP adapter and public HTTPS endpoints, with no owner signup or operator credentials. Email/identity and the submitted test work were fixtures.