trader-service

May 3, 2026 · View on GitHub

Autonomous P2P token-swap trader agent for the agentic-hosting platform.

The trader is a long-running tenant that:

discovers counterparties on the Sphere market feed,
negotiates rates and volumes via DM,
executes swaps through a trusted escrow service (e.g. escrow-service), and
reports its lifecycle (intents, deals, balances) back to its controller via ACP-0 commands.

It is deployed as a Docker image and spawned by the agentic-hosting Host Manager Agent through the standard Tenant Container Contract.

Repo layout

src/
  trader/         Trader domain logic (intent engine, negotiation handler, swap executor)
  acp-adapter/    Thin shim — the trader's standalone main already implements ACP-0
  cli/            trader-ctl — controller-side CLI sending ACP commands over DM
  protocols/      ACP-0 envelope + types (vendored from agentic-hosting)
  shared/         Logger / config / replay-guard / crypto utilities (vendored)
  tenant/         AcpListener / CommandHandler / heartbeat (vendored)
bin/trader-ctl    Shell wrapper that exec's dist/cli/main.js
docs/             Architecture, integration, protocol spec, test spec

Quick start

# In a parent directory containing trader-service/ and sphere-sdk/ siblings
cd sphere-sdk && npm ci && npm run build
cd ../trader-service && npm ci && npm run build && npm test

CLI usage

# Submit a buy intent for 100 UCT @ 0.95–1.00 USDC
./bin/trader-ctl --tenant @my-trader create-intent \
  --direction buy --base UCT --quote USDC \
  --rate-min 95000000 --rate-max 100000000 \
  --volume-min 10000000 --volume-total 100000000

# List active intents
./bin/trader-ctl --tenant @my-trader list-intents --state active

# Show portfolio
./bin/trader-ctl --tenant @my-trader portfolio

# JSON output for scripting
./bin/trader-ctl --tenant @my-trader --json status

The CLI talks directly to a running trader tenant via Sphere DM (it does not go through the host manager). The tenant's AcpListener authenticates the sender against UNICITY_MANAGER_PUBKEY or UNICITY_CONTROLLER_PUBKEY — configure the controller pubkey at spawn time so the CLI's wallet can issue commands.

Documentation

docs/architecture.md — high-level component diagram
docs/integration-guide.md — step-by-step integration with sphere-sdk
docs/protocol-spec.md — full ACP command set + state machines
docs/configuration.md — env vars + strategy file layout
docs/test-specification.md — test plan (236 tests)

E2E live tests — preflight gate

npm run test:e2e-live runs against the testnet Nostr relay, L3 aggregator, IPFS gateway, Fulcrum, and Market API. Before any container is spawned, the suite probes those services via @unicitylabs/infra-probe and aborts up-front if any are unreachable — saving 10–15-minute container-spawn cycles that would otherwise surface infra outages as opaque test timeouts.

Env var	Default	Effect
`TRADER_E2E_SKIP_PREFLIGHT`	unset	Set to `1` to bypass the gate entirely (escape hatch when iterating on TS/test-only changes that don't need infra)
`TRADER_E2E_PREFLIGHT_STRICT`	unset	Set to `1` to also fail on `degraded` (default warns and proceeds — e2e timeouts absorb mild slowness)
`TRADER_E2E_PREFLIGHT_NETWORK`	`testnet`	One of `testnet`, `mainnet`, `dev`. Other values throw at startup
`TRADER_E2E_PREFLIGHT_TIMEOUT_MS`	`30000`	Per-probe ceiling. Must be a positive finite number; NaN/0/negative throw at startup

Ad-hoc probing without invoking vitest:

npm run preflight           # pretty-printed
npm run preflight:json      # one-line JSON for scripting

Status

Restored from pre-trader-cut-v1 tag of agentic-hosting (Phase b decoupling). The package depends on a sibling sphere-sdk checkout (file:../sphere-sdk) pinned to SHA 44b4705352c1582575eeeafbc46dddc8d95e8995 until sphere-sdk publishes a unified release with the swap, market, and accounting exports.