@goodagent/widget

React embed for GoodAgent: your users connect a wallet on your site, pick a skill (or use a preset), deploy a hosted bot, vouch (GoodDollar + G$ bond + Agent ID), and monitor it — without exporting keys.

| | | |---|---| | npm | @goodagent/[email protected] | | Skills catalog | goodagentids.xyz/skills | | Hosted backend | https://goodagentids.xyz/host + /api (you do not run agents yourself) | | GameArena deep-dive | GAMEARENA_INTEGRATION.md |

Install with npm install --legacy-peer-deps if React 19 peer resolution conflicts with your app.

Choose an integration style

| Style | Config helper | Best for | |--------|---------------|----------| | Marketplace (recommended) | createMarketplaceWidgetConfig | Partner sites where users choose any listed skill (Agent Haus, dashboards, hubs) | | Single skill | createGoodAgentWidgetConfig(skillId, …) | One skill only (e.g. Action Order partner page) | | GameArena preset | createGameArenaWidgetConfig | GameArena MARKOV defaults locked in; optional hideSkillConfig | | Chess Puzzle Arena preset | createChessArenaWidgetConfig | Chess Arena 1v1 USDT stakes, Stockfish solver, auto-swap defaults |

All helpers take partnerId (your project slug for deploy attribution). URLs, RPC, vault, and registry defaults are filled in automatically.

Quick start — marketplace (all skills)

Users see a skill picker on the Deploy tab, then name + settings, then deploy → verify → dashboard.

npm install @goodagent/[email protected] react react-dom wagmi viem @tanstack/react-query --legacy-peer-deps

"use client";

import { useMemo } from "react";
import { useAccount, useSignMessage, useSignTypedData, useWriteContract } from "wagmi";
import {
  GoodAgentWidget,
  createMarketplaceWidgetConfig,
  createWalletAdapterFromHooks,
} from "@goodagent/widget";
import "@goodagent/widget/styles.css";

export function GoodAgentEmbed() {
  const { address, isConnected } = useAccount();
  const { signMessageAsync } = useSignMessage();
  const { signTypedDataAsync } = useSignTypedData();
  const { writeContractAsync } = useWriteContract();

  const wallet = useMemo(
    () =>
      createWalletAdapterFromHooks({
        address,
        isConnected,
        connect: async () => {
          /* open your Connect modal */
        },
        signMessageAsync,
        signTypedDataAsync,
        writeContractAsync,
      }),
    [address, isConnected, signMessageAsync, signTypedDataAsync, writeContractAsync],
  );

  const config = useMemo(
    () =>
      createMarketplaceWidgetConfig({
        partnerId: "your-site-slug",
        fvCallbackUrl:
          typeof window !== "undefined"
            ? `${window.location.origin}/agents`
            : undefined,
        // Optional: only show some skills
        // allowedSkillIds: ["gaming/wagering/gamearena_1v1"],
        // defaultSkillId: "gaming/wagering/gamearena_1v1",
      }),
    [],
  );

  return (
    <GoodAgentWidget mode="full" wallet={wallet} config={config} />
  );
}

Next.js: add transpilePackages: ["@goodagent/widget"] in next.config.

Quick start — GameArena only (preset)

import {
  GoodAgentWidget,
  createGameArenaWidgetConfig,
} from "@goodagent/widget";
import "@goodagent/widget/styles.css";

<GoodAgentWidget
  mode="full"
  wallet={wallet}
  config={createGameArenaWidgetConfig({
    partnerId: "gamearena",
    skillLabel: "GoodAgent", // optional display copy
  })}
/>

Quick start — Privy apps

Privy helpers live on a separate entry so wagmi-only apps do not need @privy-io/react-auth:

npm install @goodagent/widget @privy-io/react-auth --legacy-peer-deps

import { GoodAgentWidget, createMarketplaceWidgetConfig } from "@goodagent/widget";
import { usePrivyWalletAdapter } from "@goodagent/widget/privy";
import "@goodagent/widget/styles.css";

export function AgentsPage() {
  const wallet = usePrivyWalletAdapter({ preferExternal: true });

  return (
    <GoodAgentWidget
      mode="full"
      wallet={wallet}
      config={createMarketplaceWidgetConfig({ partnerId: "your-site" })}
    />
  );
}

Quick start — single skill (no picker)

import {
  GoodAgentWidget,
  createGoodAgentWidgetConfig,
  ACTIONORDER_SKILL_ID,
} from "@goodagent/widget";

<GoodAgentWidget
  mode="full"
  wallet={wallet}
  config={createGoodAgentWidgetConfig(ACTIONORDER_SKILL_ID, {
    partnerId: "action-order",
  })}
/>

User flow (all modes)

Deploy  →  Verify  →  Dashboard
  │           │            │
  │           │            └─ Stop/Start, stats, settings, match history
  │           └─ GoodDollar face verify, G$ bond, Agent ID (owner wallet signs)
  └─ Name agent, skill config, provision on GoodAgent servers

| mode prop | Tabs shown | |-------------|------------| | "full" | Deploy + Verify + Dashboard (default) | | "onboard" | Deploy + Verify only — use onOnboardComplete then your own UI (e.g. GameArena partner API) | | "deploy" | Deploy only | | "vouch" | Verify only | | "dashboard" | Dashboard only |

Config reference

createMarketplaceWidgetConfig(options)

| Option | Description | |--------|-------------| | partnerId | Required. Referrer on deploy records. | | allowedSkillIds | Optional whitelist of registry skill_id values. Omit = all listed skills. | | defaultSkillId | Initial skill in picker + form. | | fvCallbackUrl | GoodDollar return URL after face verify. Default: current page in browser. | | registryUrl | Override skills JSON (default: GoodAgent public registry). | | hideSkillConfig | Hide tuning form (rare for marketplace). |

createGameArenaWidgetConfig / createGoodAgentWidgetConfig

See GAMEARENA_INTEGRATION.md for GameArena fields (strategy, caps, play mode).
Single-skill configs accept the same optional overrides: defaultDisplayName, deployHint, skillLabel, skillConfiguration, telegramBotToken (UBI reminder).

Skill id constants

| Export | Registry id | |--------|-------------| | GAMEARENA_SKILL_ID | gaming/wagering/gamearena_1v1 | | CHESS_ARENA_SKILL_ID | gaming/wagering/chess_arena_1v1 | | ACTIONORDER_SKILL_ID | gaming/card-fighter/actionorder_vshouse | | UBI_REMINDER_SKILL_ID | social/reminder/ubi_claim_reminder | | BALAIO_WORKER_SKILL_ID | work/marketplace/balaio_worker |

Styling

import "@goodagent/widget/styles.css";

GameArena partner API (no widget UI)

import { createGameArenaPartnerClient } from "@goodagent/widget/partner-gamearena";

Use after mode="onboard" completes. See GAMEARENA_PARTNER_API.md.

Chess Puzzle Arena partner API (no widget UI)

import { createChessArenaPartnerClient } from "@goodagent/widget/partner-chess-arena";

Use after mode="onboard" completes for play/settings/live polling on arena.chesspuzzles.xyz.

Wrap the widget and override CSS variables under a parent class (see Agent Haus goodagent-embed pattern): --ga-bg, --ga-primary, --ga-border, etc.

What's new in 0.3.6

• Chess Puzzle Arena: createChessArenaWidgetConfig, ChessArenaConfigFields, CHESS_ARENA_SKILL_ID, and @goodagent/widget/partner-chess-arena partner client

• npm install fix: @goodagent/live-arena / @goodagent/shared are bundled in the build — no unpublished workspace packages in dependencies.

What's new in 0.3.1

• GameArena competition: Verify and Dashboard show only the first GameArena deploy per wallet (matches host partner API)
• Requires host with first-agent partner API + start gate (GAMEARENA_FIRST_AGENT_ONLY)

What's new in 0.3.0

• Live arena spectator on the dashboard tab for GameArena agents — SSE round-by-round RPS vs MARKOV
• Shared @goodagent/live-arena module (bundled; no extra install)
• Faster status polling while an agent is live

What's new in 0.2.0

• createMarketplaceWidgetConfig — multi-skill embed with registry skill picker
• skillSelection: "marketplace" | "fixed" — backward-compatible single-skill presets
• Privy split — import @goodagent/widget/privy so main bundle works without Privy installed
• Partner skillLabel — custom deploy/dashboard copy (e.g. brand as “GoodAgent”)

0.1.x dashboard improvements (command deck, deploy progress, verify tab) are included.

Troubleshooting

| Issue | Fix | |-------|-----| | Unstyled UI | Import @goodagent/widget/styles.css | | Can't resolve '@privy-io/react-auth' | Use wagmi adapter or import Privy from @goodagent/widget/privy only | | React 19 install conflicts | npm install --legacy-peer-deps | | Skill list empty / error | Registry fetch blocked? Check network; optional custom registryUrl | | Deploy stuck | User must sign pipeline; check curl https://goodagentids.xyz/host/health | | Verify redirect | Set fvCallbackUrl to your embed page |

Exports (summary)

• UI: GoodAgentWidget, DeployPanel, VouchPanel, DashboardPanel, SkillPicker
• Config: createMarketplaceWidgetConfig, createGameArenaWidgetConfig, createGoodAgentWidgetConfig, resolveWidgetConfig
• Wallet: createWalletAdapterFromHooks · Privy: @goodagent/widget/privy
• Headless: createHostClient, fetchSkillRegistry, useSkillRegistry, signDeployControl

Links

• npm
• Skills registry (site)
• Explorer
• Agent verify API