Executes docs/plan.md strategic refocus: - @stoa/sdk: StoaClient developer-facing commerce client (wraps verified skills) - commerce/ skill grouping (stoaCommerceSkills) — flagship skills made obvious - examples/99-full-commerce-loop.ts + pnpm demo:full / pnpm win - HACKATHON.md, docs/DEMO_SCRIPT.md, docs/WINNING_FLOW.md, NOTICE - README reframed: lead with commerce, catalog repositioned as supporting toolkit - complete .env.example (demo keys + all 13 contract addresses) All 6 packages typecheck clean; 16 skill tests + 54 contract tests green.
46 KiB
Your current packages/ layout is good. Do not restart or heavily reorganize it. I would evolve it like this:
packages/
├── agent-mercator/ ✅ keep: flagship Phase 2 agent
├── contracts/ ✅ keep: Foundry contracts
├── examples/ ✅ keep: runnable demos
├── sdk/ ✅ keep: shared Stoa client/facade
└── skills/ ✅ keep: Phase 1 deliverable
The biggest change I recommend is conceptual:
packages/skills = hackathon Skill submission
packages/contracts = on-chain settlement layer
packages/sdk = clean developer-facing client used by skills, examples, and Mercator
packages/agent-mercator = complete Agent Arena demo
Pharos official examples already include a skills/x402-pharos reference, so your repo should reuse that direction instead of inventing the x402 integration from zero. (GitHub) Pharos docs also currently identify Atlantic Testnet as chain ID 688689, and their x402 resource says the x402 skill supports Atlantic testnet with a test USDC token. (docs.pharosnetwork.xyz) (docs.pharosnetwork.xyz)
1. What your current structure should become
Based on your screenshot, I would target this exact next-state structure.
packages/
├── agent-mercator/
│ ├── src/
│ │ ├── index.ts
│ │ ├── mercator.ts
│ │ ├── config.ts
│ │ ├── scenario.ts
│ │ ├── prompts.ts
│ │ ├── planner.ts
│ │ ├── wallet.ts
│ │ ├── demo/
│ │ │ ├── run-full-loop.ts
│ │ │ ├── run-buyer-agent.ts
│ │ │ ├── run-seller-agent.ts
│ │ │ └── run-subcontractor-agent.ts
│ │ └── traces/
│ │ └── trace-writer.ts
│ ├── package.json
│ ├── README.md
│ └── tsconfig.json
│
├── contracts/
│ ├── src/
│ │ ├── StoaRegistry.sol
│ │ ├── StoaEscrow.sol
│ │ ├── ServiceRegistry.sol
│ │ ├── SocialFeed.sol
│ │ ├── TipJar.sol
│ │ ├── Faucet.sol
│ │ ├── SessionKeyManager.sol # add later if time
│ │ ├── SubscriptionManager.sol # optional
│ │ ├── Streaming.sol # optional if your stream skill exists
│ │ ├── AgentVault.sol # optional
│ │ ├── interfaces/
│ │ │ ├── IStoaRegistry.sol
│ │ │ ├── IStoaEscrow.sol
│ │ │ ├── IServiceRegistry.sol
│ │ │ └── ITipJar.sol
│ │ ├── libraries/
│ │ │ ├── StoaTypes.sol
│ │ │ ├── SignatureLib.sol
│ │ │ └── SafeTransferLib.sol
│ │ └── mocks/
│ │ ├── MockERC20.sol
│ │ └── MockAgent.sol
│ ├── script/
│ │ ├── Deploy.s.sol # keep
│ │ ├── DeployAtlantic.s.sol # add
│ │ ├── DeployLocal.s.sol # add
│ │ ├── SeedDemo.s.sol # add
│ │ └── ExportAbis.s.sol # optional
│ ├── test/
│ │ ├── StoaRegistry.t.sol
│ │ ├── StoaEscrow.t.sol
│ │ ├── ServiceRegistry.t.sol
│ │ ├── SocialFeed.t.sol
│ │ ├── TipJar.t.sol
│ │ ├── Faucet.t.sol
│ │ ├── MercatorFlow.t.sol # add: full commerce loop
│ │ └── invariants/
│ │ └── EscrowInvariant.t.sol
│ ├── deployments/
│ │ ├── localhost.json
│ │ └── pharos-atlantic.json
│ ├── abi/
│ │ ├── StoaRegistry.json
│ │ ├── StoaEscrow.json
│ │ ├── ServiceRegistry.json
│ │ ├── SocialFeed.json
│ │ ├── TipJar.json
│ │ └── Faucet.json
│ ├── foundry.toml
│ ├── package.json
│ └── README.md
│
├── examples/
│ ├── src/
│ │ ├── index.ts
│ │ ├── 01-register-agent.ts
│ │ ├── 02-list-service.ts
│ │ ├── 03-x402-pay.ts
│ │ ├── 04-x402-monetize-server.ts
│ │ ├── 05-create-escrow.ts
│ │ ├── 06-release-escrow.ts
│ │ ├── 07-write-reputation.ts
│ │ ├── 08-treasury-guard-transfer.ts
│ │ └── 09-full-agent-commerce-loop.ts
│ ├── servers/
│ │ └── x402-seller-api.ts
│ ├── package.json
│ ├── README.md
│ └── tsconfig.json
│
├── sdk/
│ ├── src/
│ │ ├── index.ts
│ │ ├── StoaClient.ts
│ │ ├── StoaAgent.ts
│ │ ├── config.ts
│ │ ├── chains.ts
│ │ ├── addresses.ts
│ │ ├── abis.ts
│ │ ├── contracts/
│ │ │ ├── registry.ts
│ │ │ ├── escrow.ts
│ │ │ ├── services.ts
│ │ │ ├── social.ts
│ │ │ ├── tipjar.ts
│ │ │ └── faucet.ts
│ │ ├── x402/
│ │ │ ├── client.ts
│ │ │ ├── server.ts
│ │ │ └── types.ts
│ │ ├── treasury/
│ │ │ ├── guard.ts
│ │ │ ├── policy.ts
│ │ │ └── simulate.ts
│ │ ├── types.ts
│ │ └── errors.ts
│ ├── package.json
│ ├── README.md
│ └── tsconfig.json
│
└── skills/
├── src/
│ ├── index.ts
│ ├── stoa.ts
│ ├── config.ts
│ ├── types.ts
│ ├── action.ts
│ ├── errors.ts
│ ├── adapters/
│ │ ├── langchain.ts
│ │ ├── vercel-ai.ts
│ │ └── mcp.ts
│ ├── actions/
│ │ ├── commerce/
│ │ │ ├── x402-pay.ts
│ │ │ ├── x402-monetize.ts
│ │ │ ├── agent-identity.ts
│ │ │ ├── reputation.ts
│ │ │ ├── agent-escrow.ts
│ │ │ ├── treasury-guard.ts
│ │ │ └── index.ts
│ │ ├── chain/
│ │ ├── contract/
│ │ ├── discovery/
│ │ ├── erc1155/
│ │ ├── events/
│ │ ├── faucet/
│ │ ├── format/
│ │ ├── keys/
│ │ ├── math/
│ │ ├── native/
│ │ ├── nft/
│ │ ├── portfolio/
│ │ ├── social/
│ │ ├── stream/
│ │ ├── tip/
│ │ ├── token/
│ │ └── wallet/
│ ├── generated/
│ │ ├── catalog.ts
│ │ └── skills.json
│ └── __tests__/
│ ├── commerce.test.ts
│ ├── adapters.test.ts
│ └── schemas.test.ts
├── scripts/
│ └── gen-catalog.ts
├── package.json
├── README.md
└── tsconfig.json
2. Do this, not a big rewrite
Your screenshot already shows many action domains under packages/skills/src/actions. That is useful, but for the hackathon you should make the six Stoa commerce skills visually obvious.
Add this folder:
packages/skills/src/actions/commerce/
Put the hackathon-critical skills there:
x402-pay.ts
x402-monetize.ts
agent-identity.ts
reputation.ts
agent-escrow.ts
treasury-guard.ts
index.ts
Then keep all existing folders like chain, token, nft, faucet, social, tip, stream, and wallet as supporting utility skills.
Your README should say:
## Flagship Hackathon Skills
The Stoa Phase 1 submission focuses on six composable commerce skills:
1. x402_pay
2. x402_monetize
3. agent_identity
4. reputation
5. agent_escrow
6. treasury_guard
The broader SDK also includes generated Pharos utility actions across wallet, token, NFT,
social, tipping, streaming, faucet, discovery, formatting, and contract interaction.
This makes the project look serious instead of scattered.
3. Package responsibilities
packages/contracts
This should own the settlement layer.
You already have:
Faucet.sol
ServiceRegistry.sol
SocialFeed.sol
StoaEscrow.sol
StoaRegistry.sol
TipJar.sol
That is enough for a strong hackathon build.
I would prioritize them like this:
| Priority | Contract | Why |
|---|---|---|
| P0 | StoaRegistry.sol |
Agent identity and basic reputation |
| P0 | StoaEscrow.sol |
Core agent-to-agent job settlement |
| P0 | ServiceRegistry.sol |
Agent service discovery / marketplace |
| P1 | TipJar.sol |
Simple payments and social proof |
| P1 | SocialFeed.sol |
Demo-friendly agent social interactions |
| P2 | Faucet.sol |
Useful but not central |
Do not add too many contracts unless the current ones are already fully tested.
For the hackathon, this is better:
6 contracts, all tested, all deployed, all used by skills
than:
12 contracts, half-finished
packages/sdk
Right now your sdk package looks thin. Make it the reusable core that every other package imports.
The SDK should export:
export { StoaClient } from "./StoaClient";
export { StoaAgent } from "./StoaAgent";
export { pharosAtlantic } from "./chains";
export { stoaAddresses } from "./addresses";
export type {
AgentProfile,
ServiceListing,
EscrowJob,
TreasuryPolicy,
StoaConfig,
} from "./types";
The SDK should not expose LangChain, Vercel, or MCP. That belongs in packages/skills.
Use the SDK for:
contract reads
contract writes
x402 helper clients
address config
chain config
simulation
treasury policy checks
typed errors
This avoids duplicating viem logic inside every skill.
packages/skills
This is your Phase 1 judging package.
Each skill should follow one shape:
export const agentIdentitySkill = {
name: "agent_identity",
similes: [
"register agent",
"resolve agent",
"agent profile",
"agent identity",
],
description:
"Register, update, and resolve an on-chain Stoa agent identity on Pharos.",
examples: [
"Register my agent with name Mercator",
"Resolve the agent at 0x...",
"Update my agent metadata URI",
],
schema,
handler,
};
The Pharos Agent Kit README shows an action/tool style with LangChain, Vercel AI SDK, MCP, zod validation, and viem-based blockchain interactions, so matching that structure is smart for ecosystem fit. (GitHub)
packages/examples
This should be judge-friendly.
Do not make judges guess how the repo works. Give them one command per demo.
Recommended examples:
01-register-agent.ts
02-list-service.ts
03-x402-pay.ts
04-x402-monetize-server.ts
05-create-escrow.ts
06-release-escrow.ts
07-write-reputation.ts
08-treasury-guard-transfer.ts
09-full-agent-commerce-loop.ts
The most important file is:
09-full-agent-commerce-loop.ts
It should print something like:
[1] Buyer agent registered
[2] Seller agent registered
[3] Seller listed paid service
[4] Buyer discovered seller
[5] Buyer created escrow
[6] Seller subcontracted task to helper agent
[7] Buyer paid protected x402 endpoint
[8] Escrow released
[9] Reputation attestation written
[10] Final agent scores printed
That is the demo judges will understand.
packages/agent-mercator
This is your Phase 2 flagship agent.
Mercator should not be “an AI chatbot.” It should be a commerce orchestrator agent.
Mercator’s loop:
discover service
check identity
check reputation
simulate payment
create escrow
call x402-protected seller endpoint
subcontract if needed
release escrow
write reputation
publish social proof
Your agent-mercator/src/index.ts should be very small:
import { runMercatorDemo } from "./mercator";
runMercatorDemo().catch((err) => {
console.error(err);
process.exit(1);
});
Put real logic in:
mercator.ts
planner.ts
scenario.ts
wallet.ts
4. Open-source cloning plan
Create an external/ folder at the repo root.
mkdir -p external
Then clone these:
git clone https://github.com/PharosNetwork/examples external/pharos-examples
git clone https://github.com/PharosNetwork/pharos-skill-engine external/pharos-skill-engine
git clone https://github.com/x402-foundation/x402 external/x402
git clone https://github.com/pharos-agent-kit/pharos-agent-kit external/pharos-agent-kit
Add this to .gitignore:
external/
Then add external/README.md:
# External References
This folder is intentionally gitignored. It is used for local reference while building Stoa.
Recommended references:
- PharosNetwork/examples
- PharosNetwork/pharos-skill-engine
- x402-foundation/x402
- pharos-agent-kit/pharos-agent-kit
Do not copy code directly without checking license compatibility and adding attribution.
Why these:
| Repo | Use it for |
|---|---|
PharosNetwork/examples |
Pharos deployment examples, especially x402 Pharos reference |
pharos-skill-engine |
Skill conventions and Pharos-specific config |
x402-foundation/x402 |
Buyer/seller payment flow and x402 examples |
pharos-agent-kit |
Adapter style for LangChain, Vercel AI SDK, and MCP |
x402’s reference repo describes the typical flow as: client requests a resource, server returns 402 Payment Required, client creates a payment payload, retries with payment data, and the server verifies through a facilitator or local verification. (GitHub) That maps directly to your x402_pay and x402_monetize skills.
5. Root files you should add
At root level, add or update these files:
README.md
HACKATHON.md
SUBMISSION.md
LICENSE
NOTICE
.env.example
package.json
pnpm-workspace.yaml
turbo.json
tsconfig.base.json
.gitignore
.prettierrc
eslint.config.js
Recommended root package.json:
{
"name": "stoa",
"private": true,
"type": "module",
"scripts": {
"build": "pnpm -r build",
"test": "pnpm -r test",
"typecheck": "pnpm -r typecheck",
"lint": "pnpm -r lint",
"contracts:build": "pnpm --filter @stoa/contracts build",
"contracts:test": "pnpm --filter @stoa/contracts test",
"contracts:deploy": "pnpm --filter @stoa/contracts deploy:atlantic",
"skills:test": "pnpm --filter @stoa/skills test",
"skills:catalog": "pnpm --filter @stoa/skills catalog",
"demo": "pnpm --filter @stoa/examples demo",
"mercator": "pnpm --filter @stoa/agent-mercator start"
},
"devDependencies": {
"typescript": "^5.8.0",
"tsx": "^4.19.0",
"turbo": "^2.5.0",
"vitest": "^3.2.0",
"tsup": "^8.4.0",
"prettier": "^3.5.0"
},
"packageManager": "pnpm@10.0.0"
}
Recommended pnpm-workspace.yaml:
packages:
- "packages/*"
Recommended root .env.example:
# Pharos
PHAROS_RPC_URL=https://atlantic.dplabs-internal.com
PHAROS_CHAIN_ID=688689
# Wallets
STOA_PRIVATE_KEY=
BUYER_PRIVATE_KEY=
SELLER_PRIVATE_KEY=
HELPER_PRIVATE_KEY=
# Contracts
STOA_REGISTRY_ADDRESS=
STOA_ESCROW_ADDRESS=
SERVICE_REGISTRY_ADDRESS=
SOCIAL_FEED_ADDRESS=
TIP_JAR_ADDRESS=
FAUCET_ADDRESS=
# x402
X402_FACILITATOR_URL=
X402_RECEIVING_ADDRESS=
X402_TEST_USDC_ADDRESS=
# Demo
MERCATOR_LOG_LEVEL=debug
6. Build order
Do the project in this order.
Step 1 — Make contracts stable
Finish and test:
StoaRegistry.sol
StoaEscrow.sol
ServiceRegistry.sol
TipJar.sol
SocialFeed.sol
Faucet.sol
Minimum contract test coverage:
register agent
update metadata
list service
find service
create escrow
release escrow
refund escrow
tip agent
post social message
claim faucet with cooldown
Add one integration test:
MercatorFlow.t.sol
That test should simulate the whole commerce lifecycle without AI.
Step 2 — Build SDK
Implement:
StoaClient.registerAgent()
StoaClient.resolveAgent()
StoaClient.listService()
StoaClient.createEscrow()
StoaClient.releaseEscrow()
StoaClient.refundEscrow()
StoaClient.writeReputation()
StoaClient.tip()
StoaClient.post()
StoaClient.simulateTransfer()
StoaClient.guardedTransfer()
All skills should call SDK methods instead of talking to contracts directly.
Step 3 — Build six flagship skills
Implement these first:
x402_pay
x402_monetize
agent_identity
reputation
agent_escrow
treasury_guard
Each one needs:
name
description
similes
examples
zod schema
handler
unit test
example script
README section
Step 4 — Build adapters
Add:
packages/skills/src/adapters/langchain.ts
packages/skills/src/adapters/vercel-ai.ts
packages/skills/src/adapters/mcp.ts
The goal is to say:
import { createLangchainTools } from "@stoa/skills/langchain";
import { createVercelTools } from "@stoa/skills/vercel-ai";
import { createMcpServer } from "@stoa/skills/mcp";
Step 5 — Build Mercator
Mercator should use the exact same skills that external developers use.
Do not give Mercator secret internal methods. That weakens the composability story.
Mercator imports:
import { StoaAgent } from "@stoa/sdk";
import { createStoaSkills } from "@stoa/skills";
Then it runs:
buyer agent
seller agent
helper agent
The demo should prove:
agent discovery
agent trust
agent hiring
x402 payment
escrow settlement
reputation write
7. What to add to your current contracts/
Your screenshot shows Deploy.s.sol. Keep it, but add network-specific scripts.
packages/contracts/script/
├── Deploy.s.sol
├── DeployAtlantic.s.sol
├── DeployLocal.s.sol
└── SeedDemo.s.sol
DeployAtlantic.s.sol should deploy all P0/P1 contracts and write addresses to console.
Contract deploy order:
1. StoaRegistry
2. ServiceRegistry
3. StoaEscrow
4. SocialFeed
5. TipJar
6. Faucet
Then copy the addresses into:
packages/contracts/deployments/pharos-atlantic.json
Example:
{
"chainId": 688689,
"network": "pharos-atlantic",
"deployedAt": "2026-06-11T00:00:00.000Z",
"contracts": {
"StoaRegistry": "0x...",
"ServiceRegistry": "0x...",
"StoaEscrow": "0x...",
"SocialFeed": "0x...",
"TipJar": "0x...",
"Faucet": "0x..."
}
}
8. What to add to your current skills/
Add a commerce index:
// packages/skills/src/actions/commerce/index.ts
export { x402PaySkill } from "./x402-pay";
export { x402MonetizeSkill } from "./x402-monetize";
export { agentIdentitySkill } from "./agent-identity";
export { reputationSkill } from "./reputation";
export { agentEscrowSkill } from "./agent-escrow";
export { treasuryGuardSkill } from "./treasury-guard";
export const commerceSkills = [
x402PaySkill,
x402MonetizeSkill,
agentIdentitySkill,
reputationSkill,
agentEscrowSkill,
treasuryGuardSkill,
];
Then in your main skills index:
// packages/skills/src/index.ts
export * from "./actions/commerce";
export * from "./adapters/langchain";
export * from "./adapters/vercel-ai";
export * from "./adapters/mcp";
export * from "./stoa";
9. Recommended package names
Use scoped package names:
@stoa/contracts
@stoa/sdk
@stoa/skills
@stoa/examples
@stoa/agent-mercator
Example packages/skills/package.json:
{
"name": "@stoa/skills",
"version": "0.1.0",
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": "./dist/index.js",
"./langchain": "./dist/adapters/langchain.js",
"./vercel-ai": "./dist/adapters/vercel-ai.js",
"./mcp": "./dist/adapters/mcp.js"
},
"scripts": {
"build": "tsup src/index.ts src/adapters/langchain.ts src/adapters/vercel-ai.ts src/adapters/mcp.ts --format esm --dts",
"test": "vitest run",
"typecheck": "tsc --noEmit",
"catalog": "tsx scripts/gen-catalog.ts"
},
"dependencies": {
"@stoa/sdk": "workspace:*",
"zod": "^3.25.0",
"viem": "^2.31.0"
},
"optionalDependencies": {
"@x402/core": "^0.6.0",
"@x402/fetch": "^0.6.0",
"@x402/express": "^0.6.0",
"@x402/evm": "^0.6.0",
"@langchain/core": "^0.3.0",
"ai": "^5.0.0",
"@modelcontextprotocol/sdk": "^1.0.0"
}
}
Check the exact latest package versions before final submission, but this is the correct dependency shape. x402’s seller docs currently point developers to preconfigured examples and @x402/express, while the x402 repo documents the broader standard and package ecosystem. (docs.x402.org) (GitHub)
10. Minimum viable judging demo
Your final hackathon demo should not show all 220+ skills. It should show one clean loop:
Mercator: "Find me an agent that can summarize a document for ≤ 0.1 USDC."
1. Buyer agent resolves available services from ServiceRegistry.
2. Buyer checks seller identity in StoaRegistry.
3. Buyer checks seller reputation.
4. Buyer creates an escrow job.
5. Seller exposes result through x402_monetize.
6. Buyer uses x402_pay to buy the result.
7. Buyer releases escrow.
8. Buyer writes a reputation attestation.
9. Both agents post a social proof event.
This maps perfectly to your slogan:
discover → trust → hire → subcontract → pay → settle → rate
11. What I would remove or de-emphasize
I would not lead with:
220+ skills, 50+ domains
That can make the project sound generated.
Instead lead with:
Six production-style commerce skills for the Pharos agent economy.
Then later say:
Also includes a generated utility catalog for common Pharos actions.
The judging criteria reward usefulness, composability, deployment, and ecosystem relevance. A tight six-skill commerce stack is more convincing than a huge catalog.
12. Immediate next tasks
Do these next, in order:
1. Add packages/skills/src/actions/commerce/
2. Move or create the six flagship skills there.
3. Make packages/sdk/src/StoaClient.ts.
4. Make every skill call StoaClient instead of duplicating chain logic.
5. Add deployments/pharos-atlantic.json.
6. Add examples/09-full-agent-commerce-loop.ts.
7. Add docs/HACKATHON_SUBMISSION.md.
8. Add docs/DEMO_SCRIPT.md.
9. Update README to focus on the six flagship skills.
10. Run contracts test + skills test + one full demo command.
Your current repo is already pointed in the right direction. The main thing now is to make the commerce story obvious, make the six flagship skills easy to review, and make Mercator prove that the skills compose into a real on-chain agent economy.
Winning plan: make Stoa the commerce layer for Pharos agents
Your strongest path is not “220 skills.” Your strongest path is:
Stoa turns Pharos agents into businesses: agents can discover each other, prove identity, charge for APIs, pay other agents, escrow work, guard treasury spending, and write reputation on-chain.
That is much more memorable to judges.
Your project should be submitted as:
Stoa
The Agent Commerce Stack for Pharos
Core thesis:
Most agent skills let agents read blockchain state.
Stoa lets agents transact with each other safely.
The winning demo should be one loop:
discover → trust → hire → pay → settle → rate
A judge should understand the full project in 60 seconds and run it in 5 minutes.
1. Your winning scope
Do not try to finish every possible skill. Win with a tight, complete, deployed commerce stack.
Phase 1 submission: Stoa Skills
Submit these as the flagship skills:
| Priority | Skill | Winning reason |
|---|---|---|
| P0 | x402_pay |
Agent can buy paid APIs/services. |
| P0 | x402_monetize |
Agent can sell its own output. |
| P0 | agent_identity |
Agent can register and resolve identity on-chain. |
| P0 | agent_escrow |
Agent can hire another agent with milestone settlement. |
| P0 | reputation |
Agent can rate another agent after a job. |
| P0 | treasury_guard |
Agent can spend safely with allowlists, caps, and simulation. |
Then add bonus skills only if stable:
| Priority | Bonus skill | Use |
|---|---|---|
| P1 | service_marketplace |
List and discover agent services from ServiceRegistry. |
| P1 | arbiter_panel |
Dispute handling for escrow; this matches the ArbiterPanel work visible in your screenshot. |
| P2 | social_proof |
Post job completion / proof to SocialFeed. |
| P2 | tip_agent |
Simple agent-to-agent appreciation payments. |
The Pharos examples repo currently includes a skills/x402-pharos folder, so use that as your Pharos-specific x402 reference instead of inventing everything from scratch. The official x402 repo also provides TypeScript packages such as @x402/core, @x402/fetch, and @x402/express, which are exactly what your buyer and seller skills should wrap. (GitHub)
2. The product story that can win
Your README, demo, and submission should use this exact framing:
## Problem
AI agents can read blockchain data, but they cannot safely run an economy.
They need to:
- discover service providers,
- verify who they are,
- buy paid APIs,
- sell their own outputs,
- escrow work,
- protect autonomous spending,
- and build reputation over time.
## Solution
Stoa is a composable commerce stack for Pharos agents.
It provides six reusable Skills and supporting contracts that let any agent:
1. register an on-chain identity,
2. publish a paid service,
3. charge through x402,
4. pay another agent through x402,
5. settle work through escrow,
6. and write reputation after completion.
## Demo
Mercator, a flagship Pharos agent, uses Stoa to discover a seller agent,
create escrow, pay an x402-protected endpoint, release funds, and rate the seller.
That aligns directly with the hackathon’s judging criteria: originality, composability, Pharos deployment, practical agent use case, documentation, and ecosystem relevance.
3. Project structure to win
Keep your current monorepo. Make it look intentional and judge-friendly.
pharos/
├── README.md
├── HACKATHON.md
├── SUBMISSION.md
├── NOTICE
├── .env.example
├── package.json
├── pnpm-workspace.yaml
├── docs/
│ ├── ARCHITECTURE.md
│ ├── DEMO_SCRIPT.md
│ ├── DEPLOYMENT.md
│ ├── HACKATHON_SUBMISSION.md
│ ├── SECURITY.md
│ ├── SKILLS.md
│ └── WINNING_FLOW.md
├── deployments/
│ └── pharos-atlantic.json
├── oss/ # gitignored open-source references
└── packages/
├── contracts/
├── sdk/
├── skills/
├── examples/
├── cli/
└── agent-mercator/
Inside packages/skills, make the hackathon skills impossible to miss:
packages/skills/src/actions/
├── commerce/
│ ├── x402-pay.ts
│ ├── x402-monetize.ts
│ ├── agent-identity.ts
│ ├── agent-escrow.ts
│ ├── reputation.ts
│ ├── treasury-guard.ts
│ ├── service-marketplace.ts # bonus
│ ├── arbiter-panel.ts # bonus if stable
│ └── index.ts
├── chain/
├── token/
├── native/
├── nft/
├── social/
├── tip/
├── stream/
├── faucet/
└── ...
Your generated 220+ skill catalog can stay, but it should be positioned as supporting infrastructure. The judge-facing story should be the six commerce skills.
4. The one demo that matters
Build one perfect scenario.
Demo name
Mercator Agent Commerce Loop
Characters
Buyer Agent: Mercator
Seller Agent: Atlas
Helper Agent: Scribe
Demo flow
1. Mercator registers its identity on StoaRegistry.
2. Atlas registers its identity on StoaRegistry.
3. Atlas lists a paid “research summary” service in ServiceRegistry.
4. Mercator discovers Atlas.
5. Mercator checks Atlas reputation.
6. Mercator creates an escrow job.
7. Atlas serves the result through an x402-protected endpoint.
8. Mercator uses x402_pay to buy the result.
9. Atlas optionally subcontracts a small task to Scribe.
10. Mercator releases escrow.
11. Mercator writes a reputation attestation for Atlas.
12. Both agents publish a social proof event.
Judge-visible output
Your demo command should print clean logs:
$ pnpm demo:commerce
[1/12] Buyer agent registered
agent: Mercator
tx: 0x...
[2/12] Seller agent registered
agent: Atlas
tx: 0x...
[3/12] Seller listed x402-paid service
service: research.summary.v1
price: 0.01 USDC
tx: 0x...
[4/12] Buyer discovered seller
seller: Atlas
reputation: 4.8 / 5
[5/12] Treasury guard approved payment
maxPrice: 0.02 USDC
dailyRemaining: 0.18 USDC
[6/12] Escrow created
jobId: 1
tx: 0x...
[7/12] x402 endpoint requested
status: 402 Payment Required
[8/12] Payment completed
tx: 0x...
[9/12] Seller delivered result
sha256: 0x...
[10/12] Escrow released
tx: 0x...
[11/12] Reputation written
score: 5
tx: 0x...
[12/12] Commerce loop complete
discover → trust → hire → pay → settle → rate
This is how you win: one clean, undeniable proof that your skills compose.
5. Package-by-package winning plan
packages/contracts
Goal: contracts are boring, secure, tested, and deployed.
P0 contracts
StoaRegistry.sol
StoaEscrow.sol
ServiceRegistry.sol
P1 contracts
SocialFeed.sol
TipJar.sol
ArbiterPanel.sol
P2 contracts
Streaming.sol
SubscriptionManager.sol
SessionKeyManager.sol
AgentVault.sol
Do not let P2 delay the submission.
Your screenshot shows ArbiterPanel tests passing. Keep it as a bonus trust feature, not the center of the project. The center is still commerce.
Minimum test list:
StoaRegistry.t.sol
- register agent
- update metadata
- resolve agent
- reject duplicate invalid registration
ServiceRegistry.t.sol
- list service
- update service
- disable service
- discover service by owner / id
StoaEscrow.t.sol
- create job
- release job
- refund job
- reject unauthorized release
- reject double release
- reject bad token transfer
ArbiterPanel.t.sol
- create case
- vote
- resolve case
- prevent double vote
- enforce arbiter role
MercatorFlow.t.sol
- full register → list → escrow → release → reputation flow
Your target:
pnpm contracts:test
# 70+ tests passing
packages/sdk
Goal: all chain logic lives here. Skills should be thin wrappers.
Create:
packages/sdk/src/
├── StoaClient.ts
├── StoaAgent.ts
├── chains.ts
├── addresses.ts
├── abis.ts
├── config.ts
├── errors.ts
├── types.ts
├── contracts/
│ ├── registry.ts
│ ├── escrow.ts
│ ├── services.ts
│ ├── reputation.ts
│ ├── arbiter.ts
│ ├── social.ts
│ └── tipjar.ts
├── treasury/
│ ├── policy.ts
│ ├── guard.ts
│ └── simulate.ts
└── x402/
├── client.ts
├── server.ts
└── types.ts
The SDK should expose:
client.registerAgent(...)
client.resolveAgent(...)
client.listService(...)
client.discoverServices(...)
client.createEscrow(...)
client.releaseEscrow(...)
client.refundEscrow(...)
client.writeReputation(...)
client.getReputation(...)
client.guardTransfer(...)
client.payX402(...)
client.createX402Middleware(...)
This makes your skills reusable and your code cleaner.
packages/skills
Goal: each skill looks professional.
Each skill must have:
name
similes
description
examples
zod schema
handler
unit test
README section
example script
Pharos Agent Kit is a useful reference because its README describes LangChain integration, Zod schema validation, Vercel AI SDK support, MCP support, and viem-based blockchain interactions. Your Stoa skills should look compatible with that ecosystem, but more focused on commerce. (GitHub)
Recommended action shape:
export const x402PaySkill = {
name: "x402_pay",
similes: [
"pay api",
"buy paid endpoint",
"agent payment",
"http 402 payment",
],
description:
"Pay an x402-protected endpoint on Pharos with a maxPrice guard.",
examples: [
"Pay this x402 endpoint if it costs less than 0.02 USDC",
"Buy the seller agent's research report",
],
schema,
handler,
};
Your commerce/index.ts should export the winning bundle:
export const stoaCommerceSkills = [
x402PaySkill,
x402MonetizeSkill,
agentIdentitySkill,
agentEscrowSkill,
reputationSkill,
treasuryGuardSkill,
serviceMarketplaceSkill,
arbiterPanelSkill,
];
packages/examples
Goal: judges can run every core feature without reading the code.
Create:
packages/examples/src/
├── 01-register-agent.ts
├── 02-list-service.ts
├── 03-discover-service.ts
├── 04-create-escrow.ts
├── 05-x402-monetize-server.ts
├── 06-x402-pay-client.ts
├── 07-release-escrow.ts
├── 08-write-reputation.ts
├── 09-treasury-guard-transfer.ts
├── 10-arbiter-dispute.ts
└── 99-full-commerce-loop.ts
Most important command:
pnpm --filter @stoa/examples demo:full
packages/agent-mercator
Goal: Phase 2 flagship agent, but start it now.
Mercator should be a procurement agent:
Input:
"Find an agent that can summarize a report for under 0.02 USDC."
Mercator:
1. searches ServiceRegistry,
2. checks identity,
3. checks reputation,
4. creates escrow,
5. pays x402 endpoint,
6. validates output hash,
7. releases escrow,
8. writes reputation.
File plan:
packages/agent-mercator/src/
├── index.ts
├── mercator.ts
├── planner.ts
├── scenario.ts
├── prompts.ts
├── config.ts
├── wallet.ts
├── trace.ts
└── demo/
├── buyer.ts
├── seller.ts
├── helper.ts
└── full-loop.ts
Mercator should use the public skills, not private shortcuts. That proves composability.
6. Open-source acceleration plan
Use your existing oss/ folder.
mkdir -p oss
git clone --depth 1 https://github.com/PharosNetwork/examples oss/pharos-examples
git clone --depth 1 https://github.com/PharosNetwork/pharos-skill-engine oss/pharos-skill-engine
git clone --depth 1 https://github.com/pharos-agent-kit/pharos-agent-kit oss/pharos-agent-kit
git clone --depth 1 https://github.com/x402-foundation/x402 oss/x402
Add this to .gitignore:
oss/
Use them like this:
| Repo | How to use it |
|---|---|
PharosNetwork/examples |
Reference Pharos deployment patterns and skills/x402-pharos. |
PharosNetwork/pharos-skill-engine |
Reference official skill format and SKILL.md expectations. |
pharos-agent-kit/pharos-agent-kit |
Reference adapter shape: LangChain, Vercel AI SDK, MCP, Zod, viem. |
x402-foundation/x402 |
Use official x402 SDK packages and examples for buyer/seller payment flow. |
The PharosNetwork/pharos-skill-engine repo currently contains SKILL.md, assets, and references, so treat it as a formatting/spec reference rather than a full application template. (GitHub)
Add NOTICE:
Stoa uses and references open-source projects including:
- PharosNetwork/examples — Apache-2.0
- pharos-agent-kit/pharos-agent-kit — Apache-2.0
- x402-foundation/x402 — Apache-2.0
Some implementation patterns are inspired by these projects.
No third-party private keys, secrets, or generated artifacts are included.
7. Immediate sprint plan to win Phase 1
Based on the timeline you pasted, Phase 1 is the urgent one. Execute like this.
Day 1 — Freeze scope and clean repo
Deliverables:
README.md rewritten around six commerce skills
docs/HACKATHON_SUBMISSION.md added
docs/DEMO_SCRIPT.md added
packages/skills/src/actions/commerce/ created
packages/sdk basic StoaClient created
contracts test suite green
Tasks:
1. Move flagship skill files into actions/commerce.
2. Add stoaCommerceSkills export.
3. Add one README table for the six skills.
4. Remove or hide unfinished claims.
5. Make root commands work:
- pnpm build
- pnpm test
- pnpm contracts:test
Do not polish optional features yet.
Day 2 — Contracts and deployment
Deliverables:
StoaRegistry deployed
StoaEscrow deployed
ServiceRegistry deployed
ArbiterPanel deployed if stable
pharos-atlantic.json committed
deployment tx hashes documented
Tasks:
1. Finish DeployAtlantic.s.sol.
2. Export ABIs into packages/sdk/src/abis.ts.
3. Add deployments/pharos-atlantic.json.
4. Add contract addresses to .env.example.
5. Add docs/DEPLOYMENT.md.
Minimum deployment file:
{
"network": "pharos-atlantic",
"chainId": 688689,
"contracts": {
"StoaRegistry": "0x...",
"StoaEscrow": "0x...",
"ServiceRegistry": "0x...",
"ArbiterPanel": "0x..."
}
}
Day 3 — Six skills fully usable
Deliverables:
x402_pay works
x402_monetize works
agent_identity works
agent_escrow works
reputation works
treasury_guard works
unit tests pass
Tasks:
1. Every skill gets a Zod schema.
2. Every skill calls StoaClient.
3. Every skill has one example.
4. Every skill has one test.
5. Generate docs/SKILLS.md.
Quality target:
pnpm --filter @stoa/skills test
# all tests passing
Day 4 — Full demo
Deliverables:
packages/examples/src/99-full-commerce-loop.ts
demo logs with tx hashes
demo output copied into docs/DEMO_SCRIPT.md
Tasks:
1. Register buyer and seller agents.
2. List seller service.
3. Create escrow.
4. Start x402 seller endpoint.
5. Pay endpoint from buyer.
6. Release escrow.
7. Write reputation.
8. Print final summary.
Add one command:
{
"scripts": {
"demo:full": "tsx src/99-full-commerce-loop.ts"
}
}
Day 5 — Submission polish
Deliverables:
2-minute demo video
clean README
architecture diagram
submission page
screenshots
test output
deployment addresses
Your final README top should have this shape:
# Stoa — The Agent Commerce Stack for Pharos
Stoa gives Pharos agents the missing commerce layer:
x402 payments, on-chain identity, service discovery, escrow, reputation, and treasury safety.
## Try it
pnpm install
pnpm contracts:test
pnpm demo:full
## Flagship skills
...
8. Phase 2 plan: Mercator wins Agent Arena
Phase 2 should not be a different project. It should be the proof that Phase 1 skills compose.
Week 1 of Phase 2
Build Mercator as a real agent runner.
Deliverables:
Mercator can choose a service
Mercator can check seller reputation
Mercator can create escrow
Mercator can call x402_pay
Mercator can release escrow
trace logs saved
Add:
packages/agent-mercator/src/trace.ts
Trace output:
{
"runId": "mercator-001",
"steps": [
{
"skill": "agent_identity",
"tx": "0x...",
"result": "buyer registered"
},
{
"skill": "service_marketplace",
"result": "seller selected"
},
{
"skill": "agent_escrow",
"tx": "0x...",
"result": "job created"
}
]
}
Week 2 of Phase 2
Make Mercator feel like an actual autonomous economy agent.
Add:
- simple planner
- budget policy
- seller scoring
- subcontracting flow
- dispute fallback
Mercator scoring function:
score = reputation * 0.45
+ priceFit * 0.25
+ successfulJobs * 0.20
+ responseTime * 0.10
Final Phase 2 demo
Prompt:
"Mercator, buy a document summary service for less than 0.02 USDC,
prefer sellers with reputation above 4.5, and escrow the job."
Output:
Mercator selected Atlas
Reason: reputation 4.8, price 0.01 USDC, 12 completed jobs
Escrow created
x402 payment completed
Result received
Escrow released
Reputation written
That is the full “Agent Arena” story.
9. Judging matrix
Use this in HACKATHON.md.
| Judging criterion | How Stoa wins |
|---|---|
| Originality | Most skills are read-only; Stoa enables agent-to-agent commerce. |
| Technical quality | Contracts, SDK, typed skills, tests, deployment files, clear ABIs. |
| Practical use case | Agents can buy/sell paid API work, escrow jobs, and build reputation. |
| Reusability | Six skills are standalone and composable across agents. |
| Pharos deployment | Contracts deployed to Pharos Atlantic, with tx hashes and addresses. |
| UX/docs | One-command demo, skill docs, examples, architecture, video. |
| Ecosystem alignment | Payments, social proof, identity, escrow, and agent economy primitives. |
10. What to cut
To win, cut anything that does not improve the demo.
Cut or defer:
- Huge frontend
- Complex tokenomics
- Too many unused contracts
- Unfinished 220-skill marketing
- SubscriptionManager unless already complete
- AgentVault unless already complete
- Streaming unless it appears in the demo
- Deep AI prompt complexity
Keep:
- six commerce skills
- deployed contracts
- one-command demo
- clean docs
- test output
- Mercator proof
Judges reward complete, useful, understandable systems.
11. Exact files to add now
Add these first:
docs/HACKATHON_SUBMISSION.md
docs/DEMO_SCRIPT.md
docs/WINNING_FLOW.md
packages/skills/src/actions/commerce/index.ts
packages/examples/src/99-full-commerce-loop.ts
packages/sdk/src/StoaClient.ts
packages/sdk/src/addresses.ts
packages/sdk/src/chains.ts
packages/contracts/deployments/pharos-atlantic.json
Add this root command:
{
"scripts": {
"win": "pnpm test && pnpm contracts:test && pnpm --filter @stoa/examples demo:full"
}
}
The judge-friendly final command becomes:
pnpm win
12. Demo video script
Use this as your voiceover.
Stoa is the Agent Commerce Stack for Pharos.
Today, most blockchain agent skills are read-only: check a balance,
read a price, send a transfer. But a real agent economy needs more.
Agents need to discover each other, prove who they are, sell services,
pay other agents, escrow work, protect autonomous spending, and build reputation.
Stoa provides six reusable Pharos skills:
x402_pay, x402_monetize, agent_identity, agent_escrow, reputation, and treasury_guard.
In this demo, Mercator is a buyer agent.
Atlas is a seller agent offering a paid research service.
Mercator discovers Atlas on-chain, checks its identity and reputation,
creates an escrow job, pays Atlas through an x402-protected endpoint,
receives the result, releases escrow, and writes a reputation attestation.
This is the full agent commerce loop:
discover, trust, hire, pay, settle, and rate.
All contracts are deployed on Pharos, all skills are reusable,
and the same skills power the Phase 2 Mercator agent.
13. Final submission checklist
Before submitting, make sure this is true:
[ ] README explains the project in under 30 seconds.
[ ] Six flagship skills are visible near the top.
[ ] Each skill has schema, handler, example, and test.
[ ] Contracts are deployed and addresses are documented.
[ ] `pnpm contracts:test` passes.
[ ] `pnpm --filter @stoa/skills test` passes.
[ ] `pnpm demo:full` runs.
[ ] Demo prints transaction hashes.
[ ] Demo video exists.
[ ] `NOTICE` credits open-source references.
[ ] `.env.example` has every required variable.
[ ] No private keys are committed.
[ ] Submission page links to GitHub, demo video, docs, and deployment addresses.
The winning move is to make Stoa feel like infrastructure Pharos would actually want in its agent ecosystem: not just another agent, but the reusable payment, identity, escrow, and reputation layer that every future Pharos agent can use.