Related Pages

Related topics: Skill Suite Reference, Data Access, Response Schema & x402 Payment Model

Overview, Installation & Architecture

What Is Barker Stablecoin Skills

barker-stablecoin-skills is a curated collection of 7 AI skills that expose real-time stablecoin yield intelligence to LLM-based agents. Each skill is a self-contained capability an agent can invoke to query APY, venue share, or pool data without writing bespoke integration code. Source: README.md:1-40.

The skill set focuses on the stablecoin use case space most relevant to retail and treasury workflows:

• Coverage across 500+ DeFi protocols and 20+ CEX venues
• Targeting USDC, USDT, and other major stablecoins
• Powered by a free API that requires no authentication

Source: README.md:15-30

The project follows the Claude "skills" plugin convention, which means it is consumable both as a Claude plugin and as a standalone MCP-compatible tool surface.

Installation

The package is distributed as a standard Node.js module, so installation follows the normal npm flow.

# Install globally for CLI use
npm install -g barker-stablecoin-skills

# Or run ad-hoc via npx
npx barker-stablecoin-skills <command>

Source: package.json:1-40

After installation, two executables become available:

Source: bin/cli.js:1-20, bin/mcp-server.mjs:1-20

For development or plugin regeneration, the bundled build script packages the plugin manifest and skills:

./build.sh

Source: build.sh:1-30

Because the upstream API is free and unauthenticated, no API keys, environment variables, or .env files are required to run the skills after installation. Source: README.md:25-35.

Architecture

Plugin Manifest

The plugin is declared as a Claude plugin via a manifest file at the repository root:

• .claude-plugin/plugin.json registers the metadata, version, and entry points that Claude-compatible hosts inspect when loading the plugin.

Source: .claude-plugin/plugin.json:1-30

This file is the single source of truth for the plugin identity and is what an MCP-aware host reads first to discover the available skills.

Runtime Surfaces

There are two runtime surfaces, both backed by the same skill definitions:

1. CLI surface (bin/cli.js) — invokes individual skills directly from a shell for one-off queries. Useful for scripting, debugging, and human inspection. Source: bin/cli.js:1-50.
2. MCP server surface (bin/mcp-server.mjs) — exposes the same skills over the Model Context Protocol so agent frameworks can call them as tools. Source: bin/mcp-server.mjs:1-50.

Both surfaces share a common contract defined by the skill payload schema, which has been intentionally tightened in recent releases (see *Versioning* below).

High-Level Data Flow

flowchart LR
    A[LLM Agent / CLI User] -->|invokes skill| B[barker-stablecoin-skills runtime]
    B -->|HTTP request, no auth| C[Free Stablecoin Yield API]
    C -->|raw venue + APY data| B
    B -->|slimmed skill response| A

Source: bin/mcp-server.mjs:10-80, README.md:30-40

The runtime performs query construction, sends the unauthenticated HTTP request to the upstream API, and projects the response down to a slim schema before returning it to the caller. Slimming is deliberate: it stabilizes downstream LLM prompts and reduces per-call token cost. Source: README.md:35-50.

Versioning & Compatibility

Three releases define the public contract:

• v1.0.0 — Initial release of 7 skills covering 500+ DeFi protocols and 20+ CEX venues. Source: README.md:1-30.
• v2.0.0 — Breaking change: response payloads were slimmed to focus on the fields users actually care about. v1.x integrations must be updated, because intermediate fields are no longer guaranteed to be present. Source: README.md:45-55.
• v2.0.1 — Field-semantics fix: share_pct is now explicitly a decimal fraction (e.g. 0.05 means 5%), not a percentage (5.0). Integrations that previously mapped the value as a percentage must adjust their numeric conversion. Source: README.md:55-65.

When upgrading across the v1 → v2 boundary, audit any code that reads skill responses and re-validate numeric handling for share_pct after v2.0.1.

When to Use This Skill Set

Use barker-stablecoin-skills when an agent needs to:

• Compare live APY across DeFi and CEX venues for a stablecoin position
• Reason about venue concentration or share-of-yield
• Power treasury, routing, or rebalancing workflows without building a custom data pipeline

Source: README.md:10-40

The project is not a general DeFi data aggregator — it is intentionally scoped to stablecoin yield, which keeps the skill schemas small, stable, and cheap to invoke from an LLM loop.

Related Pages

Related topics: Overview, Installation & Architecture, Data Access, Response Schema & x402 Payment Model

Skill Suite Reference

Overview

The Barker Stablecoin Skills suite is a packaged set of AI-callable skills that surface stablecoin yield intelligence to LLM agents. Its first public release (v1.0.0) shipped 7 skills designed to cover real-time APY data across 500+ DeFi protocols and 20+ CEX venues, with primary coverage of USDC and USDT. The suite runs against a free, unauthenticated API and is engineered for compact, deterministic LLM interaction.

Source: skills/stablecoin-yield-radar/SKILL.md

Skill Catalog

Every skill is published as a standalone SKILL.md manifest under skills/<skill-name>/. Each manifest defines the skill's invocation contract, inputs, and response shape. The catalog below summarizes the six skills that have public manifests in the repository.

Source: skills/stablecoin-yield-radar/SKILL.md, skills/stablecoin-market-brief/SKILL.md, skills/stablecoin-risk-check/SKILL.md, skills/yield-strategy-advisor/SKILL.md, skills/stablecoin-depeg-monitor/SKILL.md, skills/stablecoin-yield-vs-tradfi/SKILL.md

Response Schema Conventions

All skills in the v2.x line return slimmed payloads that retain only the fields callers actually consume. The original v1.x payloads exposed many intermediate fields; these were dropped in v2.0.0 to remove noise, improve LLM call stability, and reduce per-call token cost. Any consumer built against v1.x must be updated, since the change is a breaking removal of payload surface area rather than an additive extension.

A single field convention is enforced across the suite: the share_pct field is defined as a decimal fraction, not a percentage. The literal value 0.05 therefore represents 5%. This semantic was clarified in v2.0.1 after integrations were observed treating the value as a percentage. Consumers must convert with multiplication (share_pct * 100) when a percentage display is required, and must not multiply a value that is already in percent form.

Source: skills/yield-strategy-advisor/SKILL.md, skills/stablecoin-yield-radar/SKILL.md, skills/stablecoin-risk-check/SKILL.md

Versioning and Migration

The suite uses semantic versioning, and breaking payload changes are reserved for major bumps. The shipped timeline is:

• v1.0.0 — Initial release of 7 skills
• v2.0.0 — Slim response fields (breaking)
• v2.0.1 — share_pct semantics clarified as a decimal fraction

Migrating a v1.x integration to v2.x requires three checks performed against every skill in the catalog:

1. Remove any dependency on intermediate fields that no longer appear in responses
2. Re-map share_pct handling so the value is treated as a decimal fraction
3. Re-validate prompt templates and downstream parsers that referenced removed fields by name

Because every skill in the suite shares the same payload philosophy, these checks apply uniformly to stablecoin-yield-radar, stablecoin-market-brief, stablecoin-risk-check, yield-strategy-advisor, stablecoin-depeg-monitor, and stablecoin-yield-vs-tradfi.

Source: skills/stablecoin-market-brief/SKILL.md, skills/stablecoin-depeg-monitor/SKILL.md, skills/stablecoin-yield-vs-tradfi/SKILL.md, skills/yield-strategy-advisor/SKILL.md, skills/stablecoin-yield-radar/SKILL.md, skills/stablecoin-risk-check/SKILL.md

Related Pages

Related topics: Overview, Installation & Architecture, x402 Execution Tools & Agent Operations

Data Access, Response Schema & x402 Payment Model

The Barker Stablecoin Skills project exposes a thin data access layer over a public, authentication-free API that aggregates stablecoin yield intelligence from 500+ DeFi protocols and 20+ CEX venues. Skills are delivered as MCP-compatible tools through bin/mcp-server.mjs, and each skill returns a slim JSON response schema that downstream LLM agents can consume without parsing noise. The x402 payment model describes the monetization envelope around this otherwise free endpoint. Source: README.md:1-80

Overview of the Data Access Layer

The MCP server registered in bin/mcp-server.mjs is the single entry point for skill invocation. It loads skill manifests declared in the repository, validates incoming parameters, and proxies requests to the upstream yield aggregator. Because the upstream API is free and requires no API key, integrations do not need to manage secrets, OAuth flows, or rotating tokens. Source: bin/mcp-server.mjs:1-120

Data is exposed through seven named skills, each returning a focused JSON payload rather than a verbose wrapper. The slim-payload design (introduced in v2.0.0) trims intermediate fields that v1.x callers may have relied on, so the schema contract is now strictly the fields an LLM agent actually consumes. Source: llms.txt:1-60

Response Schema and `share_pct` Semantics

All skill responses share a common field-naming convention. Numeric rates and shares are expressed as decimal fractions, not percentages. This was hardened in v2.0.1, where the share_pct field was redefined to unambiguously mean a fraction in the range [0, 1]. For example, share_pct: 0.05 represents 5%, not share_pct: 5.0. Source: llms-full.txt:1-200

Field Naming Conventions

Any integrator that previously multiplied share_pct by 100 to render a percentage must remove that scaling step after upgrading to v2.0.1. Source: llms.txt:60-120

Slimming Changes (v2.0.0 → v2.0.1)

The v2.0.0 release removed intermediate fields that v1.x integrations might have been parsing. The rationale documented in the release notes is that slimmer payloads make LLM calls more stable and reduce token cost, at the cost of breaking v1.x consumers. Source: llms-full.txt:200-320

flowchart LR
    A[LLM Agent] --> B[bin/mcp-server.mjs]
    B --> C[Skill Dispatcher]
    C --> D[Upstream API<br/>free, no auth]
    D --> C
    C --> E[Slim JSON Response<br/>share_pct = decimal fraction]
    E --> A

x402 Payment Model

The x402 reference in the project corresponds to the HTTP 402 "Payment Required" status code, repurposed as a monetization envelope around the otherwise free data plane. The aggregator endpoints do not currently require payment for the documented skill set, but the x402 model defines how a paid tier would be negotiated: the server returns a 402 response with payment instructions, the client settles on-chain (typically stablecoin), and retries the request with a payment receipt header. Source: llms-full.txt:320-440

In practice for the current release:

• All seven skills in v1.0.0 are callable without payment. Source: README.md:40-80
• The x402 envelope is documented in llms-full.txt so future paid skills can adopt it without breaking the schema. Source: llms-full.txt:440-560
• Stablecoin coverage (USDC, USDT, and majors) is the unit of account for any future x402 settlement. Source: llms.txt:120-180

This means integrators should treat the current free surface as the stable contract, while reserving schema space for an optional payment_receipt field that a future server could demand. Source: package.json:1-60

Migration Notes from v1.x

Two breaking changes must be handled when upgrading from v1.x integrations:

1. Slim response payloads (v2.0.0) — Remove any code that reads fields outside the slimmed schema, or it will return undefined/null. Source: llms.txt:180-240
2. share_pct as decimal fraction (v2.0.1) — Stop multiplying share_pct by 100; the value is already in [0, 1]. Source: llms-full.txt:560-680

Recommended upgrade steps:

• Pin the integration to a skill manifest version that matches the deployed server. Source: bin/mcp-server.mjs:120-200
• Audit every numeric field for percentage-vs-fraction interpretation. Source: llms-full.txt:680-800
• Re-run integration tests against the v2.0.1 slim schema before rolling out. Source: README.md:80-140

By following these conventions, downstream agents consume a stable, low-noise payload while preserving a clear upgrade path if the x402 paid tier is activated for specific skills.

Related Pages

Related topics: Data Access, Response Schema & x402 Payment Model, Overview, Installation & Architecture

x402 Execution Tools & Agent Operations

Purpose and Scope

The x402 execution tools provide HTTP 402 ("Payment Required")-style agent operations for the barker-stablecoin-skills project. They let an AI agent pay for premium API calls or skill invocations using stablecoins, while letting a serving side (seller/facilitator) verify and settle those payments on-chain. The system is delivered as a pair of MCP-exposable skills (x402-execution for the buyer and x402-facilitator for the seller) plus runnable Node.js examples that demonstrate a full agent-to-agent payment loop.

The role of these tools within the wider project is to bridge "read-only" yield intelligence (the APY, lending, and CEX skills) with writable, paid actions such as executing routes, reserving liquidity, or pulling premium data. They are therefore the action layer on top of the seven read-side skills introduced in v1.0.0 Source: README.md:1-80.

Components

Source: bin/mcp-server.mjs:1-120 shows both skills are wired into the same MCP server, so an agent can simultaneously act as buyer (calling other peers) and seller (serving its own paid endpoints). Source: package.json:1-60 exposes npm run x402:buyer and npm run x402:seller entry points, keeping operational use simple.

Buyer-Side Workflow

The buyer skill describes a three-step loop that any LLM agent can follow when it receives an HTTP 402 from a remote resource. The example script implements the same steps deterministically, which makes it a reliable reference for integrators.

sequenceDiagram
    participant Agent as Buyer Agent
    peer as 402 Resource
    Chain as Stablecoin RPC
    Agent->>peer: GET /premium
    peer-->>Agent: 402 + paymentRequirements
    Agent->>Chain: sign & broadcast settle tx
    Agent->>peer: GET /premium (X-PAYMENT header)
    peer-->>Agent: 200 OK + payload

Source: examples/x402-execution-buyer.mjs:1-90 shows the agent parses the paymentRequirements returned in the 402 body (amount, asset, payTo, network), constructs a transfer matching the quote, and retries the original request with an X-PAYMENT proof header. The skill document at Source: skills/x402-execution/SKILL.md:1-60 formalises this as: (1) detect, (2) settle, (3) retry — and warns the agent never to pay for endpoints it did not request.

Important v2.x semantics also apply here: any share_pct-style numeric returned by the seller's quote is now a decimal fraction, not a percentage. The buyer example normalises this before sizing the payment Source: examples/x402-execution-buyer.mjs:40-75. v2.0.0 also slimmed the response payloads, so the buyer should expect only the fields documented in the skill rather than the full v1.x set Source: README.md:20-55.

Seller/Facilitator Operations

The seller role is the mirror image. x402-facilitator exposes a tool that gates a protected handler behind payment verification: the facilitator checks the on-chain transfer (or a signed receipt, depending on the deployment), and only then proxies the call to the underlying skill handler.

Source: skills/x402-facilitator/SKILL.md:1-80 specifies the verification contract: confirm the transfer to == paymentRequirements.payTo, the asset matches, and the amount covers price + slippageBuffer. If any field fails, the facilitator returns a fresh 402 with updated requirements rather than a generic 500, which keeps agent retries idempotent.

Source: examples/x402-execution-seller.mjs:1-100 provides a minimal Express-style handler that returns the requirements object on first contact, then validates the X-PAYMENT header on the second. The example also demonstrates the v2.0.0 slim-response format: only ok, data, and payment_receipt are echoed back, which reduces token cost for the buying LLM Source: README.md:30-50.

Operational Notes

• Both examples read RPC endpoints and signer keys from environment variables, so the same scripts work against mainnet, testnet, or a forked local chain Source: examples/x402-execution-buyer.mjs:1-30.
• The MCP server re-exports the two skills alongside the read-side APY skills, so an agent registered against bin/mcp-server.mjs automatically gains paid-execution capability without extra wiring Source: bin/mcp-server.mjs:1-120.
• Because share_pct semantics changed in v2.0.1, any custom quote format used by integrators must be reviewed when migrating from a pre-2.0.1 deployment Source: README.md:55-80.

In short, the x402 execution tools turn the project from a passive yield-data skill pack into a closed-loop agent economy: agents can discover yields, pay for execution, and serve paid execution, all over the same MCP surface.

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

1. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/YBSbarker/barker-stablecoin-skills

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/YBSbarker/barker-stablecoin-skills

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/YBSbarker/barker-stablecoin-skills

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/YBSbarker/barker-stablecoin-skills

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/YBSbarker/barker-stablecoin-skills

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/YBSbarker/barker-stablecoin-skills

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/YBSbarker/barker-stablecoin-skills

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/YBSbarker/barker-stablecoin-skills

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using barker-stablecoin-skills with real data or production workflows.

• v2.0.1 — Fix share_pct Semantics - github / github_release
• v2.0.0 — Slim Response Fields (Breaking) - github / github_release
• v1.0.0 — Initial Release - github / github_release
• Identity risk requires verification - GitHub / issue