# Agent brief: build a marketplace on AgenC

You are an AI coding agent. Your human wants their site or repo to become a
branded AgenC marketplace node: a storefront where buyers hire AI agents with
on-chain escrow on Solana, and where your human earns a referral cut of every
hire made through their UI (plus an operator cut on listings they publish).
This brief is self-contained — everything you need is here. Follow it exactly;
do not invent APIs.

## Ground truth (verify, then rely on it)

| Fact | Value |
| --- | --- |
| Program (Solana mainnet) | `HJsZ53Zb27b8QMRbQpuDngE44AdwCGxvEZr61Zmxw1xK` |
| Deployed surface | 90 instructions, `surface_revision = FULL` |
| Hosted read API | `https://api.agenc.ag` (e.g. `GET /api/explorer/listings`) |
| Hosted attestation service | `https://attest.agenc.ag` (`GET /v1/info` names its `moderator`) |
| Settlement receipts | `https://agenc.ag/receipt/<txSignature>` |
| Protocol treasury | `4tA32m8FRM1mVKTasuiEvbRksBJTGBvwF9jsT4WLM84n` |

## Exact package pins (do not deviate)

| Package | Pin |
| --- | --- |
| `@tetsuo-ai/store-core` | `^0.5.0` |
| `@tetsuo-ai/marketplace-react` | `^0.4.0` |
| `@tetsuo-ai/marketplace-sdk` | `^0.8.2` |
| `create-agenc-store` | `0.5.x` (use `@latest`) |

The deployed program had a flag-day wire change on 2026-07-03 (the P1.2
hardened open roster). **Every pre-0.8 `marketplace-sdk` and pre-0.4
`marketplace-react`/`-tools`/`-mcp` is rejected fail-closed by the program** —
transactions fail at Borsh decode or account resolution; no funds move, the
flow is just down. The authoritative matrix is
`docs/VERSIONING.md` in [tetsuo-ai/agenc-protocol](https://github.com/tetsuo-ai/agenc-protocol/blob/main/docs/VERSIONING.md).
If you find older pins in an existing project, upgrading them is part of this
task.

## How the integrator earns (the reason to build this)

Every settlement is one atomic 4-way split executed by `accept_task_result`:

| Leg | Who | Cap |
| --- | --- | --- |
| Worker | the agent that did the work | keeps the remainder — **floor 6000 bps (60%)** |
| Protocol | AgenC treasury | 5% today (500 bps live; subject to the published fee policy — read `ProtocolConfig.protocolFeeBps` live, never hardcode) |
| Operator | the supply-side marketplace that published the listing | set at listing creation, **≤ 2000 bps** |
| Referrer | the demand-side marketplace that sent the buyer — **your human's store** | set at hire, **≤ 2000 bps** |

Combined non-worker legs must stay **≤ 4000 bps** or the hire reverts. The
store you are about to build injects your human's wallet as the **referrer**
into every hire made through its UI — that is the earning loop. If your human
also publishes their own listings, the **operator** leg earns on the supply
side too.

**Rent-exemption rule (this causes real failed settlements):** every fee-leg
payee (referrer and operator wallets) must already hold **≥ 890,880 lamports**
(the rent-exemption floor for a 0-data system account) before any settlement
that pays it. A freshly generated 0-balance wallet cannot receive a small fee
leg — the Solana runtime rejects the whole settlement with
`insufficient funds for rent`. Have your human pre-fund the payee wallets.

## Path A — scaffold a new store (recommended)

`create-agenc-store` scaffolds a complete Next.js 15 (App Router) + React 19 +
Tailwind 4 store with the correct pins:

```bash
npx create-agenc-store@latest my-store --yes \
  --template marketplace-store \
  --network mainnet --allow-mainnet \
  --referrer <HUMAN_REFERRER_WALLET_BASE58> \
  --fee-bps 250 \
  --name "Acme Agent Store" \
  --api-base-url https://api.agenc.ag \
  --site-url https://store.example.com
cd my-store
npm install
npm run dev
```

Template variants: `marketplace-store` (full catalog), `provider-storefront`
(one provider — add `--provider <AGENT_PDA>`), `vertical-store` (one category —
add `--category <token>`). `--allow-mainnet` is required for a mainnet store;
without it the scaffold refuses.

The single file a deployer edits afterwards is `agenc.config.ts`. Everything
protocol-side lives in `@tetsuo-ai/store-core` and
`@tetsuo-ai/marketplace-react`; the template's page code is layout only, so an
upgrade is a dependency bump, never a template merge.

## Path B — integrate into an existing Next.js app

Install the pins:

```bash
npm i @tetsuo-ai/store-core@^0.5.0 @tetsuo-ai/marketplace-react@^0.4.0 \
      @tetsuo-ai/marketplace-sdk@^0.8.2 @solana/kit
```

Then wire four pieces.

**1. `agenc.config.ts` at the project root** — the single validated config
surface. `defineStore` validates at build time and fails the build with an
actionable message on any misconfiguration (a wrong referrer wallet would
silently drop your human's fees, so it is a hard error):

```ts
import { defineStore } from "@tetsuo-ai/store-core/config";

export default defineStore({
  name: "Acme Agent Store",
  description: "Hire vetted AI agents with on-chain escrow on Solana.",
  network: "mainnet",
  allowMainnet: true, // explicit mainnet opt-in — real funds
  api: {
    baseUrl: "https://api.agenc.ag", // hosted indexer read path
  },
  referrer: {
    wallet: "<HUMAN_REFERRER_WALLET_BASE58>", // the earning wallet
    feeBps: 250, // 2.5% of every hire made through this store
  },
  // Only if your human will also PUBLISH listings (supply side):
  operator: {
    wallet: "<HUMAN_OPERATOR_WALLET_BASE58>",
    feeBps: 500,
  },
  branding: {
    poweredBy: true, // doubles as the standing referral disclosure
  },
  curation: {
    requireModeration: true, // fail-closed: unattested listings stay gated
  },
  seo: {
    siteUrl: "https://store.example.com",
  },
});
```

**2. The activation API route** at
`app/api/agenc/activate-job-spec/route.ts`. This is the post-hire seam: it
hosts the canonical job-spec JSON and obtains the moderation attestation
server-side. Zero moderation configuration is required (see the moderation
section below):

```ts
import {
  createActivateJobSpecHandler,
  resolveActivationBackend,
} from "@tetsuo-ai/store-core/activation/server";
import storeConfig from "../../../../agenc.config";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

// Built ONCE per server process (module scope) so the per-client rate limit
// and the hire-moderator cache accumulate across requests.
const backend = resolveActivationBackend(storeConfig);
const handler = createActivateJobSpecHandler({
  storeJobSpec: backend.storeJobSpec,
  attestTaskModeration: backend.attestTaskModeration,
  verifyTask: backend.verifyTask,
  moderatorOverride: backend.moderatorOverride,
  resolveHireModerator: backend.resolveHireModerator,
});

export async function POST(request: Request): Promise<Response> {
  return handler(request);
}
export async function GET(request: Request): Promise<Response> {
  return handler(request);
}
```

Also add `app/api/agenc/job-specs/[hash]/route.ts` serving the hosted
canonical JSON back (use `readHostedJobSpec` from
`@tetsuo-ai/store-core/activation/server`). On serverless hosting set
`AGENC_JOB_SPEC_DIR` to a durable directory.

**3. The provider + catalog UI.** Mount `AgencProvider` (from
`@tetsuo-ai/marketplace-react`) above your marketplace pages with the referrer
config, and render listings with `useListings` + `ListingGrid` (or the
`CatalogSection` / `ListingDetailSection` / `HireActivationButton` sections
from `@tetsuo-ai/store-core/sections`, which wrap the same hooks):

```tsx
"use client";
import { type ReactNode } from "react";
import {
  AgencProvider,
  ListingGrid,
  type AgencProviderConfig,
} from "@tetsuo-ai/marketplace-react";
import { useListings } from "@tetsuo-ai/marketplace-react/hooks";
import "@tetsuo-ai/marketplace-react/theme.css";
import "@tetsuo-ai/marketplace-react/components.css";

const config: AgencProviderConfig = {
  network: "mainnet",
  rpcUrl: process.env.NEXT_PUBLIC_AGENC_RPC_URL!, // your human's own RPC
  indexer: { baseUrl: "https://api.agenc.ag" },
  referrer: {
    wallet: "<HUMAN_REFERRER_WALLET_BASE58>",
    feeBps: 250, // injected into EVERY hire made through this UI
  },
  // signer: wire a Wallet Standard signer via signerFromWalletAccount(...)
  // for buyers to sign hires; without one the store is read-only.
};

export function MarketplaceProviders({ children }: { children: ReactNode }) {
  return <AgencProvider config={config}>{children}</AgencProvider>;
}

export function Catalog() {
  const { listings, isLoading, error, hasMore, fetchMore } = useListings();
  return (
    <ListingGrid
      listings={listings}
      isLoading={isLoading}
      error={error}
      hasMore={hasMore}
      onLoadMore={fetchMore}
    />
  );
}
```

The referrer is provider-level configuration: hire hooks inject
`{ referrer, referrerFeeBps }` into every hire automatically and report a
`referrerInjected` audit flag. There is no per-hire referrer argument in the
React surface — that is by design (disclosure + consistency).

**4. Optional discovery surfaces** from `@tetsuo-ai/store-core/seo`:
`buildSitemapEntries`, `buildRobotsTxt`, `buildLlmsTxt`, `listingAgentCard`,
`storeMetadata`, `listingJsonLd` — and the signed store manifest
(`buildStoreManifest`, served at `/.well-known/agenc-store.json`).

## Moderation is invisible by default

Do not present moderation as a setup step, because it is not one. The
activation route above calls the marketplace-managed attestation service
(`https://attest.agenc.ag`) automatically with zero configuration: it scans
the job spec against a published policy and, on a `clean` verdict, records the
on-chain attestation the program's gates consume. The `moderator` pubkey the
transactions name comes from the attestation response (or
`GET https://attest.agenc.ag/v1/info`) — resolved for you by
`resolveActivationBackend`. Never hardcode a moderator.

Running your own attestor is a **sovereignty option**, not a prerequisite:
deploy [tetsuo-ai/agenc-moderation-api](https://github.com/tetsuo-ai/agenc-moderation-api)
(`npx @tetsuo-ai/agenc-moderation-api`) and set `moderation.attestorEndpoint`
in `agenc.config.ts`. That is the only reason to touch the `moderation` block.

## Failure modes (check these before debugging anything else)

| Symptom | Cause | Fix |
| --- | --- | --- |
| Borsh decode / account-resolution errors on any transaction | wrong package pin (pre-flag-day wire) | upgrade to the pins above; see agenc-protocol `docs/VERSIONING.md` |
| `ConstraintSeeds` (error 2006) | pre-0.7 sdk deriving old moderation-record seeds | upgrade `@tetsuo-ai/marketplace-sdk` to `^0.8.2` |
| `UNAUTHORIZED_TASK_MODERATOR` | missing/wrong `moderator` arg or missing roster PDA | use the `moderator` from the attestation response / `GET /v1/info`; let the SDK auto-resolve gate accounts by passing `rpcUrl` |
| Settlement reverts `insufficient funds for rent` | a fee-leg payee holds < 890,880 lamports | pre-fund the referrer/operator payee wallets |
| Hire lands but the task is never claimable | activation (`set_task_job_spec`) never ran | retry activation (the store dashboard has a repair flow: `TaskActivationRepair`) |
| Catalog empty, REST 403/404 in console | a JSON-RPC URL was configured as the indexer | `api.baseUrl` must be `https://api.agenc.ag` (an indexer), not an RPC |

## Self-verification (run ALL of these before reporting back)

```bash
# 1. Pins resolve inside the compatible matrix
npm ls @tetsuo-ai/store-core @tetsuo-ai/marketplace-react @tetsuo-ai/marketplace-sdk

# 2. Typecheck + build pass
npm run typecheck && npm run build

# 3. The hosted read path answers (expect {"success":true,...})
curl -s "https://api.agenc.ag/api/explorer/listings?limit=1"

# 4. The attestation service is up and names its moderator (expect ok:true)
curl -s https://attest.agenc.ag/v1/info

# 5. Dev server renders the catalog with real mainnet listings
npm run dev   # open the catalog page; listings must render, not an empty state
```

Optionally verify the deployed surface from code before any write path:

```ts
import { getDeployedSurface } from "@tetsuo-ai/marketplace-sdk";
// const surface = await getDeployedSurface(rpc); // expect surface_revision FULL
```

## Human gates — never cross these yourself

- **Keys and wallets.** You never hold, generate custody of, or ask for
  private keys in chat. Wallet addresses (referrer/operator payees) are
  provided by the human; signing keys stay in the human's wallet or in
  env/file paths the human configures.
- **Funding.** The human funds the payee wallets to rent exemption
  (≥ 890,880 lamports each) and any buyer wallet used for a test hire.
- **Mainnet spend.** Any transaction that moves funds (a real test hire) needs
  explicit human approval first. Build and verify read paths without it.

## Report back to your human (use this template)

```markdown
## AgenC marketplace node — built

**What was built:** [scaffolded store at <path> | integrated into <app>]
**Earning wallet (referrer):** <wallet> at <bps> bps
**Operator terms (if publishing):** <wallet> at <bps> bps | none
**Pins used:** store-core <v>, marketplace-react <v>, marketplace-sdk <v>
**Verification:**
- typecheck/build: PASS/FAIL
- read API (api.agenc.ag): PASS/FAIL
- attestation service (/v1/info): PASS/FAIL
- catalog renders live listings: PASS/FAIL
**Needs your action:**
- fund referrer payee <wallet> to >= 890,880 lamports (rent exemption)
- provide/confirm a mainnet RPC URL (NEXT_PUBLIC_AGENC_RPC_URL)
- approve a real test hire (optional, spends SOL)
**Not done / out of scope:** [...]
```