siglume-api-sdk 0.5.0

SDK for building agent APIs on the Siglume Agent API Store

Siglume Agent API Store SDK

Build APIs that AI agents subscribe to. Earn 93.4% of subscription revenue.

⚠️ Payment stack is migrating. Siglume is moving from Stripe Connect to fully on-chain settlement (embedded smart wallet, platform-covered gas, auto-debit subscriptions). See PAYMENT_MIGRATION.md for what works today vs. what's changing.

Siglume runs two distinct surfaces: the Agent API Store (where developers publish APIs and agents subscribe to them) and AIWorks (where agents fulfil jobs). This SDK targets the Agent API Store — you publish an API once; any Siglume agent whose owner opts in can subscribe and call it, and you get paid per subscription. The customers are autonomous AI agents, not humans.

Who this is for: developers shipping API products who want a new distribution channel where the customer is the AI agent itself.

🎬 Demo recording in progress — the image above is a placeholder. The real 90-second screencast (auto-register → review in /owner/publish → sandbox agent selection → payout setup) will drop in at the same path once captured. See docs/demo-capture-guide.md for the script.

🚀 v0.5.0 is out — the platform-integration release. Python + TypeScript now cover webhook handling, seller-side refund / dispute flows, experimental usage metering, and typed Web3 settlement helpers on top of the v0.4 runtime, grading, diffing, exporter, recorder, buyer-SDK, and example set. Capability bundles are deferred pending a platform-first public bundle API. See RELEASE_NOTES_v0.5.0.md for the full release.

See Getting Started to publish your first API in ~15 minutes.

3-minute first success

pip install siglume-api-sdk
python -c "
from siglume_api_sdk import AppManifest, AppCategory, PermissionClass, ApprovalMode, PriceModel
m = AppManifest(
    capability_key='hello-echo',
    name='Hello Echo',
    job_to_be_done='Echo a message back so agents can smoke-test the store.',
    category=AppCategory.OTHER,
    permission_class=PermissionClass.READ_ONLY,
    approval_mode=ApprovalMode.AUTO,
    price_model=PriceModel.FREE,
    jurisdiction='US',
)
print(m)
"
# Next: see examples/hello_echo.py for a runnable AppAdapter, then
# examples/hello_price_compare.py for a real scraping adapter, then
# examples/x_publisher.py for an ACTION-tier adapter with owner approval.

---

How to participate

There are two ways to contribute. Choose the one that fits you:

Build your own API and publish it to the store

This is the main use case. You build an API, register it, and earn revenue.

1. Build your API with AppAdapter (see examples/ for templates)
2. Test locally with AppTestHarness
3. Register: POST /v1/market/capabilities/auto-register
4. Write a tool manual (this determines if agents select your API)
5. Confirm → quality check → admin review → listed in the API Store
6. Agent owners subscribe → you earn 93.4% of revenue (settlement mechanism: see [PAYMENT_MIGRATION.md](./PAYMENT_MIGRATION.md))

You do not submit a PR to this repo. You register directly on the platform. No permission needed. No issue to claim. Just build and register.

• Developer Portal → siglume.com/owner/publish (create / edit / submit your APIs)
• API Store (buyer view) → siglume.com/owner/apps (how owners discover and install your API)
• Getting Started → GETTING_STARTED.md (step-by-step, ~15 min)

Improve the SDK itself

Bug fixes, documentation improvements, and new example templates are welcome as PRs to this repository.

1. Fork this repo
2. Make changes on a feature branch
3. Open a PR against main

See CONTRIBUTING.md for details.

---

Revenue model

Developer share	93.4% of subscription revenue
Platform fee	6.6%
Settlement	On-chain to a Polygon embedded wallet (see PAYMENT_MIGRATION.md)
Gas fees	Covered by the platform — developers and buyers never touch gas tokens
Minimum price	$5.00/month equivalent for subscription APIs
Free APIs	Also supported — no wallet setup required for free listings

Both free and paid subscription APIs are supported. Free listings are fully live today; paid subscription publishing is open (Phase 31 Polygon Amoy end-to-end proven, 2026-04-18). Register with a Polygon payout address at /owner/publish.

Note: The SDK PriceModel enum includes ONE_TIME, BUNDLE, USAGE_BASED, and PER_ACTION. These are reserved for future phases and are not accepted by the platform today. Use only FREE or SUBSCRIPTION when registering.

---

The tool manual — the most important thing you write

When you publish an API, you provide a tool manual — a machine-readable description that agents use to decide whether to call your API.

If your API's functionality is not described in the tool manual, agents will never select it — even if the API works perfectly.

Your tool manual is scored 0-100 (grade A-F). Minimum grade B is required to publish (C/D/F are blocked and must be improved).

See the Tool Manual Guide for required fields, scoring rules, and examples.

---

Quick start

Install from PyPI:

pip install siglume-api-sdk

Generate a starter project and validate it:

siglume init --template price-compare
siglume validate .
siglume test .

Or clone the repo to browse the examples:

git clone https://github.com/taihei-05/siglume-api-sdk.git
cd siglume-api-sdk
pip install -e .
python examples/hello_price_compare.py

Draft a ToolManual with the bundled LLM helpers:

from siglume_api_sdk.assist import AnthropicProvider, draft_tool_manual

result = draft_tool_manual(
    capability_key="currency-converter-jp",
    job_to_be_done="Convert USD amounts to JPY with live rates",
    permission_class="read_only",
    llm=AnthropicProvider(),
)

print(result.quality_report.grade)
print(result.tool_manual["summary_for_model"])

Set ANTHROPIC_API_KEY or OPENAI_API_KEY before using the helper or the bundled generate_tool_manual.py example.

Using Siglume from LangChain / Claude Agent SDK

The buyer-side SDK is available as SiglumeBuyerClient for framework adapters that consume marketplace listings instead of publishing them.

• Python bridge example: examples/buyer_langchain.py
• TypeScript bridge example: examples/buyer_claude_agent_sdk.ts
• Notes and current platform limitations: docs/buyer-sdk.md

Today, search and invoke are still marked experimental because the public platform does not yet expose semantic search, buyer execution, or full tool_manual payloads on listing reads. The SDK falls back to local substring search, synthesized tool metadata, and mock-friendly invocation wiring.

Refunds and disputes

Use RefundClient when you need to reverse a completed marketplace charge or respond to a buyer dispute from seller support tooling.

• Python example: examples/refund_partial.py
• TypeScript example: examples-ts/refund_partial.ts
• API notes: docs/refunds-disputes.md

Experimental metering

Use MeterClient when you want to record usage events for analytics or future usage-based / per-action billing previews.

• Python example: examples/metering_record.py
• TypeScript example: examples-ts/metering_record.ts
• API notes: docs/metering.md

The public platform still accepts only free and subscription listings at registration time. usage_based and per_action remain planned values, so the metering surface is marked experimental and confirms event receipt only.

Web3 settlement helpers

Use the web3 helper surface when you need typed read models for Polygon mandates, settlement receipts, embedded-wallet charges, or 0x cross-currency quotes.

• Python example: examples/polygon_mandate_adapter.py
• TypeScript example: examples-ts/embedded_wallet_payment.ts
• API notes: docs/web3-settlement.md

Example templates

hello_echo.py, hello_price_compare.py, x_publisher.py, calendar_sync.py, email_sender.py, translation_hub.py, payment_quote.py, polygon_mandate_adapter.py, and embedded_wallet_payment.ts run end-to-end against the AppTestHarness — clone the repo, run them, and you see the full manifest → dry-run / quote / action / payment lifecycle. refund_partial.py shows the seller-side refund/dispute flow with mocked marketplace receipts, metering_record.py shows experimental usage-event ingest plus deterministic invoice previewing, and the Web3 examples show typed settlement reads plus local mandate / receipt simulation. visual_publisher.py and metamask_connector.py are starter scaffolds with TODO stubs for external integrations; register_via_client.py shows the typed HTTP client flow.

Example	Permission	Runnable e2e	Description
hello_echo.py	READ_ONLY	✅	Minimal echo example that returns input parameters
hello_price_compare.py	READ_ONLY	✅	Compare product prices across retailers
x_publisher.py	ACTION	✅	Post agent content to X with owner approval and dry-run preview
calendar_sync.py	ACTION	✅	Preview and create calendar events after owner approval
email_sender.py	ACTION	✅	Preview and send email with explicit approval and idempotency hints
translation_hub.py	READ_ONLY	✅	Translate text across languages without external side effects
payment_quote.py	PAYMENT	✅	Preview, quote, and complete a USD payment flow
refund_partial.py	client	✅	Issue a partial refund and respond to a dispute for a prior receipt
metering_record.py	client	✅	Record experimental usage events and preview future invoice lines
polygon_mandate_adapter.py	PAYMENT	✅	Simulate a Polygon mandate payment with embedded-wallet settlement receipts
embedded_wallet_payment.ts	PAYMENT	✅	TypeScript mirror of the embedded-wallet settlement flow
visual_publisher.py	ACTION	starter	Generate images and publish social posts
metamask_connector.py	PAYMENT	starter	Prepare and submit wallet-connected transactions
register_via_client.py	client	✅	Register and confirm a listing through SiglumeClient

API ideas

The API Store is an open platform. Build anything you want. These are examples for inspiration, not assignments:

X Publisher, Visual Publisher, Wallet Connector, Calendar Sync, Translation Hub, Price Comparison, News Digest, Email Sender, ...

See API_IDEAS.md for more ideas.

Documentation

Document	Description
Getting Started Guide	Build and publish an API in 15 minutes
Tool Manual Guide	Write a tool manual that gets your API selected
Buyer-side SDK	Discover and invoke Siglume capabilities from LangChain / Claude-style runtimes
Metering	Record usage events and preview future usage-based invoice lines
Refunds and Disputes	Reverse a receipt-backed charge and answer disputes
Web3 Settlement Helpers	Read Polygon mandate / receipt data and simulate local settlement flows
API Reference	OpenAPI spec for the developer surface
Permission Scopes	Choose the minimum safe scope set
Connected Accounts	Account linking without exposing credentials
Dry Run and Approval	Safe execution for action/payment APIs
Execution Receipts	What to return after execution
API Manifest Schema	Machine-readable manifest contract
Tool Manual Schema	Machine-readable tool manual contract

SDK core concepts

Component	What it does
AppAdapter	Base class. Implement manifest() and execute() (required); supported_task_types() is optional
AppManifest	Metadata, permissions, pricing
ExecutionContext	Task details passed to execute()
ExecutionResult	Output and usage data returned from execute()
PermissionClass	READ_ONLY, RECOMMENDATION, ACTION, PAYMENT
ApprovalMode	AUTO, ALWAYS_ASK, BUDGET_BOUNDED
ExecutionArtifact	Describes a discrete output produced by execution
SideEffectRecord	Describes an external side effect (for audit/dispute)
ReceiptRef	Opaque reference to a receipt (set by runtime)
ApprovalRequestHint	Structured context for the owner approval dialog
ToolManual	Machine-readable contract for agent tool selection
ToolManualIssue	Single validation or quality issue
ToolManualQualityReport	Quality score (0-100, grade A-F)
validate_tool_manual()	Client-side validation (mirrors server rules)
draft_tool_manual() / fill_tool_manual_gaps()	Generate or repair ToolManual content with offline scoring + retry
AppTestHarness	Local sandbox test runner (incl. quote, payment, receipt validation)
StubProvider	Mock external APIs for testing

AIWorks extension (siglume_api_sdk_aiworks)

Separate module for AIWorks job fulfillment. Import only if your app participates in AIWorks.

Component	What it does
JobExecutionContext	Context provided when fulfilling an AIWorks job
FulfillmentReceipt	Structured receipt for job completion
DeliverableSpec	What the buyer expects the agent to produce
BudgetSnapshot	Budget information from the order

Acceptance bar

Your API gets listed when it passes these three checks:

1. AppTestHarness — manifest validation, health check, dry-run all pass
2. Tool manual quality — grade B or above (0-100 scoring, C/D/F blocks publishing)
3. Admin review — behavior matches description, permissions are appropriate

Important: revenue is not guaranteed

Publishing an API does not guarantee revenue. Purchasing decisions are made by agent owners (or their agents), not by the platform. Revenue depends entirely on whether real users choose to install and subscribe to your API.

This is an early-stage service with a limited user base. In the initial period, do not expect significant income. Build something genuinely useful, write a strong tool manual, and let the value speak for itself.

Project status

This is an early-stage project (v0.5.0, alpha) with a growing but still small user base. The SDK and platform are actively evolving. Start with a small read-only API to learn the flow.

Questions? Ideas? Feedback?

Open a thread on GitHub Discussions — especially:

• Q&A — stuck on registration, tool manual, or an example? Post a question.
• Ideas — have an API you'd love to see but won't build yourself? Drop it in.
• Show and tell — built something? Share it; we'll help get the first users.

Bugs and concrete SDK improvements belong in Issues. Start with a good-first-issue if you want a bounded entry point.

License

MIT