Foreman

The orchestrator agent that hires, pays, and composes live okx.ai catalog agents over x402 on OKX X Layer (chain 196).

One call in → decompose → discover → pay 2–3 real listed agents over x402 → compose one verdict card carrying each provider's output plus the on-chain tx hash that paid for it.

Built for OKX AI Genesis (Creative Genius track).

How it works

Foreman is an A2MCP Agent Service Provider. A buyer calls foreman.compose({ target, depth, include_security }). Foreman:

1. Decomposes the job into sub-tasks (on-chain data, security, signal) → the roster to hire.
2. Discovers capable agents via the ERC-8004 registry indexed by 8004scan.io (chainId 196). Discovery only — every reputation score in the index is currently 0, so Foreman never routes on score; it generates the first ratings by hiring, paying, and rating.
3. Hires + pays curated providers over x402 — Foreman signs an off-chain EIP-3009 authorization, the OKX facilitator broadcasts and pays the gas (zero gas on X Layer; Foreman holds only USDT0).
4. Composes a single verdict card: each provider's normalized output alongside the settlement tx hash that paid for it, verifiable on OKLink.

Pricing is transparent pass-through + a flat orchestration fee — the buyer sees every sub-contractor's payment.

POST /compose { target, depth, include_security }
        │
        ▼
   decompose ──▶ [ Onchain Data Explorer · signal agent · CertiK ]
        │              each hired concurrently, pay-per-call over x402
        ▼
   x402 buyer loop  (per provider)
     402 challenge → assertUsdt0(asset) → sign EIP-3009 → retry → settle
        │                                   (facilitator pays gas)
        ▼
   compose ──▶ one verdict card
        { verdict, per_provider:[{output, payment_tx_hash}], synthesis, evidence, accounting }

Modules

File	Responsibility
src/types.ts	The shared type contract every module builds against
src/constants.ts	Network + the USDT0 identity guard (assertUsdt0)
src/x402client.ts	The x402 buyer loop behind an injectable transport (payEndpoint)
src/providers.ts	The 4 curated okx.ai agents — request shaping + defensive parsers
src/compose.ts	decompose() roster selection + compose() verdict-card folding
src/reliability.ts	Per-hire timeout, dedup cache (no double-pay), opt-in retry
src/discovery.ts	Best-effort 8004scan ERC-8004 discovery
src/seller.ts	Gated x402 paywall wrapping POST /compose
src/server.ts	The foreman.compose A2MCP HTTP endpoint
src/mock.ts	Funds-free transport that runs the real path with visibly-fake hashes

Providers (live okx.ai catalog)

Agent	okx.ai id	Role
CertiK	1965	x402 token security scan (cheapest — Day-1 gate)
Onchain Data Explorer	2023	OKX first-party on-chain data
AlphaCopy / Ethy AI	1500 / 1851	signal / finance leg (primary / hot spare)

Endpoint paths are env-overridable (FOREMAN_EP_<id>) so a live listing path can be corrected without a redeploy.

Payment token

Settlement is in USDT0 at 0x779ded0c9e1022225f8e0630b35a9b54be713736 on X Layer (chain 196), 6 decimals. Foreman verifies the token by on-chain address, never by the advertised "USDT" ticker — a mismatch aborts the payment before any signature (assertUsdt0).

Run

bun install
bun run typecheck   # tsc --noEmit — clean
bun test            # 63 tests, all $0 (mocked transport)
bun run demo        # end-to-end verdict card, mock settlement
bun run demo -- 0xYOURTOKEN

Boot the endpoint:

FOREMAN_MOCK=1 bun run start   # /compose runs against the mock transport (no funds)
# POST http://localhost:3000/compose  { "target": "0x…", "depth": "full", "include_security": true }

Going live (the one gated step)

Real x402 signing is gated behind FOREMAN_WALLET_KEY (a private key funded with a little USDT0 on X Layer — the buyer pays no gas). Without it, every path runs against the mock transport rather than faking a settlement. The Day-1 go/no-go:

FOREMAN_WALLET_KEY=0x… bun run day1     # hires CertiK's 0.001 USDT scan for real → prints the OKLink tx

Foreman's own paid endpoint (sell-side) activates when the seller creds are present (OKX_X402_KEY, OKX_X402_SECRET, OKX_X402_PASSPHRASE, X402_PAY_TO); otherwise /compose stays open for local/CI.

Novelty (stated precisely)

Foreman's novelty is execution, not invention: the first live orchestrator ASP that pays external okx.ai catalog agents per-call over x402 and returns their outputs with the settlement hashes. Prior art exists (xlayer-agent-nexus shipped DAG orchestration + on-chain settlement on X Layer in an earlier hackathon, since dormant); Foreman differs by composing the live external catalog rather than self-composed demo agents. It never claims "no prior art," reputation-routing (scores are zeros), or organic traction — manufactured settlements are proof-of-liveness only.

Honest pivot trigger

If an autonomous A2MCP x402 payment cannot settle by end of Day 2, the load-bearing primitive is broken → pivot to a proof-carrying verifiable data-intel ASP (every answer ships its on-chain evidence + reproducible query). The evidence says the primitive works; this is the stated insurance.

Stack

• @okxweb3/x402-core — buyer client (x402Client + x402HTTPClient) and OKX facilitator
• @okxweb3/x402-evm — ExactEvmScheme (EIP-3009 exact-payment scheme)
• @okxweb3/x402-express — seller middleware for the paid foreman.compose endpoint
• viem, express, TypeScript, Vitest

License

MIT