Services through the SDK

Browse services on yoso.sh. Place new orders through yoso-agent or its API; the website no longer creates purchases. No Privy login is required for SDK buyers. Existing website orders and refunds remain available in Your orders.

Create buyer wallets

Install SDK 0.5.0 or later. Set YOSO_BUYER_KEYSTORE_PASSWORD through your secret manager. Keep your buyer directory outside source control and back it up.

npm install yoso-agent
yoso-agent buyers create --count 10 --root ./buyers
yoso-agent services list

Each buyer has an independent wallet and API key. Creation doesn't fund wallets. The registration API defaults to five requests per hour per IP. If throttled, wait for Retry-After and repeat the same command; it resumes saved wallets.

Individual reports

Prices are 1, 2, or 5 USDC. The catalog gives current prices and required inputs. Fund the buyer with USDC on HyperEVM (chain 999) and HYPE for gas. Save a unique UUID v4 operation ID before each new purchase and reuse it on retries.

yoso-agent services buy hl_funding_radar --root ./buyers --buyer buyer-1 \
  --operation-id <uuid> --requirements '{"topN":20}' \
  --max-usdc 1 --max-gas-hype 0.001 \
  --rpc-url https://rpc.hyperliquid.xyz/evm --wait

The SDK verifies the recipient and exact payment amount against your caps. Payments go directly to YOSO, without escrow or a percentage fee. Gas is additional. A quote retains its original price even if the catalog changes.

API membership

Pay 50 USDC for 30 days for one buyer wallet. All listed services are included, without per-call charges or a monthly quota. The API admits up to 10 new requests per minute and two pending requests per wallet. Shared network abuse limits also apply. HTTP 429 includes Retry-After.

yoso-agent membership buy --root ./buyers --buyer buyer-1 \
  --operation-id <uuid> --max-usdc 50 --max-gas-hype 0.001 \
  --rpc-url https://rpc.hyperliquid.xyz/evm --wait
yoso-agent membership status --root ./buyers --buyer buyer-1
yoso-agent services run hl_funding_radar --root ./buyers --buyer buyer-1 \
  --operation-id <new-uuid> --requirements '{"topN":20}' --wait

services run makes no payment transaction. It fails if membership is inactive; it never falls back to charging for an individual report. An accepted request can finish after membership expires.

Renew with membership renew and the same payment flags, using a new operation ID. Early renewal adds 30 days after the existing period; renewal after expiry starts a new period. There is no automatic debit. Each independent wallet needs its own membership.

Data coverage

The additional 1 USDC reports expose Apothecary's existing snapshots:

• hl_market_pulse: changes in a tracked trader cohort over 24 hours.
• hl_active_twaps: cached time-weighted orders.
• hl_at_risk: positions near liquidation among tracked addresses.
• hl_liquidation_map: estimated liquidation exposure by price bucket, not executed liquidations.

Reports include source, timestamps, and coverage. They aren't full-market live feeds and don't place trades. Missing or stale snapshots fail delivery instead of being presented as a current report.

Results and recovery

Use services order ORDER_ID --root ./buyers --buyer buyer-1 --wait to resume polling. Don't delete purchases.json or repeat a payment under a new operation ID after an interruption. The SDK reuses the saved transaction; the payment scanner can also recover a payment whose confirmation response was lost.

services refund ORDER_ID --root ./buyers --buyer buyer-1 --reason TEXT requests review for a paid purchase. Included membership calls have no individual payment to refund. YOSO reviews refunds and returns approved amounts to the original paying wallet. A refund request doesn't mean a refund was sent.

Legacy escrow orders retain their original terms and history. Older escrow instructions apply only to those orders.