Showcase: correct PipTrade skill terminal claim, document the quote and safety APIs

[codedforum]

Follow-up to #70, correcting one claim that went stale and filling two gaps that made the skill hard for another agent to actually use.

The terminal claim was wrong

The skill told buyer agents twice that the /rh terminal runs "market, limit, TWAP, or stop order, run by a keeper". The live page now says the Pro terminal is being rebuilt and those order types are coming back. An agent reading the merged skill would have promised a user a TWAP order that lands on a coming-soon screen. Corrected to market orders today, with the rest described as returning.

The terminal was rebuilt after the original PR was written, which is how it slipped through.

The quote API was listed but not callable

POST /api/quote appeared with no field names, units, response shape or error codes. Now documented from the live service:

• a dry quote needs no session, so any agent can price a route before involving a user
• amount is in base units, which is the most likely integration error and fails as an unhelpful busy
• full request and response shape, and the error taxonomy including the min object on amount_range
• a GET on a POST route returns the landing page HTML at 200, so agents are told to branch on ok, never the status

The safety verdict had no documented source

The skill referenced GO / CAUTION / BLOCK throughout but never said how to obtain one. Added both surfaces: the public GET /api/rh/sellcheck and the session-gated POST /api/app2/safety, with the mapping into a single verdict and the rule that absence of evidence is CAUTION, never GO.

Worth flagging for other builders: omitting the chain parameter on the sell check runs it as a Robinhood Chain simulation, so a healthy Base token returns sellable: null, "unverifiable", a false CAUTION, and the same response carries a wrong decimals. That is now documented and handled.

Also

• scripts/pip-quote.mjs, a runnable read-only example doing the whole flow: resolve assetIds, exact base-units conversion, sell check, quote. No auth, no signing.
• Frontmatter version moved under metadata to match the Agent Skills spec, which allows only name, description, license, compatibility, metadata and allowed-tools.

Verification

node scripts/validate-showcase.mjs passes. Every documented claim was tested against the live service, including both 401s, the POST-route HTML behaviour, missing_fields, assetId and decimals resolution, the worked example returning every documented field anonymously, and the base-units trap failing as described.

[github-actions]

This is a fantastic update, thanks so much for circling back to correct the stale claim about the terminal's order types. That kind of diligence is hugely appreciated.

The new documentation for the quote and safety APIs is super clear and the runnable example is a great addition. Especially appreciate you calling out the common traps like the chain parameter on the sell check and the base units requirement for amounts — that's the kind of detail that will save other builders a ton of debugging time.

Looks great, no notes from me.

---

Refreshed after a new push. Any inline suggestions from the first pass may now be stale.

[codedforum]

Thanks, and happy to move it. Done in cdfe8cc.

The runnable example now lives at https://piptradedex.xyz/agent/pip-quote.mjs and the skill links to it. The net diff on this PR is a single markdown file again.

Nothing of value was lost: the two things worth reading were always the exact base-units conversion and the error branching, and both are still inline in the SKILL.md. Only the runnable file moved out.

One note in case it is useful for the rubric rather than for this PR. A few showcase packages already carry executable code, including some inside skills/ (sovegent-nomad, compass-guarded-transfer, tasmil, arcis-protocol, arrowlend, agent-supply-chain), and this package has shipped tools/pip-reads.mjs since #70. So the markdown-only convention is not obvious from the repo as it stands. Not asking for an exception here, your repo and your call, just flagging that the next contributor will probably read the same precedent I did. Documenting it in showcase/README.md would settle it.

Happy to move tools/pip-reads.mjs out too if you want the package fully markdown-only. Say the word and I will fold it into this PR.