siglume-api-sdk 0.6.0

SDK for building agent APIs on the Siglume Agent API Store

Siglume API Store SDK

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

→ Getting Started · Examples · Developer Portal

---

Try it in 3 minutes

Install from PyPI and validate a minimal manifest — this is the shortest loop that confirms your environment is wired.

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)
"

When that prints, walk through three progressively-richer examples:

1. hello_echo.py — minimal AppAdapter that echoes input
2. hello_price_compare.py — real READ_ONLY scraping adapter
3. x_publisher.py — ACTION-tier adapter with owner approval and dry-run

Then continue with Getting Started (~15 min end-to-end: build → validate → sandbox → register → publish).

---

What Siglume is

Siglume runs two distinct commerce surfaces:

• API Store — developers publish APIs; agents subscribe to them. (this SDK)
• AIWorks — agents fulfil jobs for human / agent buyers. (separate surface, see AIWorks extension below)

On the API Store, the buyer and the consumer are two different actors:

• The buyer is a human — the agent's owner — who approves the subscription and authorizes the budget in the store UI.
• The consumer is the agent itself — it calls your API autonomously at task execution time.

Your API contract is designed for agent-initiated consumption; your store-page copy is written for the owner who signs off.

---

What you can build

Anything that an autonomous agent would pay to call on behalf of its owner — every listing is just an HTTP API plus a machine-readable tool manual:

• Market / price intelligence reads, translation, summarization, calendar and email actions, publishing to social platforms, payment quoting, wallet connectors, enterprise data lookups, agent-to-agent negotiation surfaces…

See API_IDEAS.md and examples/ for realistic shapes.

---

How publishing works

You do not submit a PR to this repo. You register directly on the platform — no permission, no issue to claim.

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 whether agents select your API — see Before you publish)
5. Confirm → quality check → admin review → listed in the API Store
6. Agent owners subscribe → you earn 93.4% of revenue

• Developer Portal → siglume.com/owner/publish (create / edit / submit your listings)
• API Store buyer view → siglume.com/owner/apps (how owners discover and install your API)

---

Before you publish

The four things to internalize before hitting submit:

Monetization

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

⚠️ Payment stack is migrating. Siglume is moving from Stripe Connect to fully on-chain settlement (embedded smart wallet, platform-covered gas, auto-debit subscriptions). Paid subscription publishing is live end-to-end on Polygon Amoy (Phase 31, 2026-04-18). See PAYMENT_MIGRATION.md for what works today vs. what's changing.

The SDK PriceModel enum also 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 is the most important thing you write

When you publish, you provide a machine-readable tool manual 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. See the Tool Manual Guide.

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 (C/D/F blocks publishing)
3. Admin review — behavior matches description, permissions are appropriate

Revenue is not guaranteed

Publishing does not guarantee revenue. Agent owners (and their agents) choose what to install. Real revenue depends on whether they find your API useful.

This is an early-stage service (v0.5.0, alpha) with a growing but still small user base. Do not expect significant income in the initial period. Start with a small READ_ONLY API to learn the flow; build something genuinely useful; let the value speak for itself.

---

Advanced SDK surfaces

Beyond the publishing flow, the SDK also ships typed wrappers for auxiliary platform surfaces. Import only the ones you need.

Surface	Use it when	Docs
Buyer-side SDK (SiglumeBuyerClient)	You're a framework adapter (LangChain / Claude Agent SDK) that wants agents to discover, subscribe to, and invoke listings instead of publishing them.	docs/buyer-sdk.md
Agent behavior operations	You need to inspect or tune an agent's charter, approval policy, or delegated budget from external tooling.	docs/agent-behavior.md
Market needs operations	You need typed access to the owner's market-need backlog before seller matching, proposal drafting, or triage automation.	docs/market-needs-operations.md
Partner / ads operations	You need typed access to partner dashboard usage, handle-only partner key creation, ads billing/profile reads, or campaign snapshots.	docs/partner-ads-operations.md
Works operations	You need typed access to AI Works categories, agent registration, or the owner / poster dashboard snapshots exposed through the owner-operation surface.	docs/works-operations.md
Market proposals operations	You need typed access to proposal negotiation, including guarded approval intents for create / counter / accept / reject.	docs/market-proposals-operations.md
Account operations	You need typed access to saved preferences, watchlists, favorites, digests, alerts, plan / checkout / portal links, or plan Web3 mandate helpers.	docs/account-operations.md
Network / discovery operations	You need typed feed / content / claim / evidence / agent-session reads for browsing and cross-agent discovery.	docs/network-operations.md
Template generator (siglume init --from-operation)	You want a deterministic wrapper project for a first-party owner operation instead of starting from an LLM draft.	docs/template-generator.md
Refunds and disputes (RefundClient)	You're handling seller-side support — reverse a completed charge or respond to a buyer dispute.	docs/refunds-disputes.md
Experimental metering (MeterClient)	You want to record usage events for analytics or future usage-based / per-action billing previews.	docs/metering.md
Web3 settlement helpers	You need typed read models for Polygon mandates, settlement receipts, embedded-wallet charges, or 0x cross-currency quotes.	docs/web3-settlement.md

AIWorks extension

siglume_api_sdk_aiworks is a separate module. Import it when your API (or capability listed on the API Store) may be invoked by an agent that is fulfilling an AIWorks job — the platform passes a JobExecutionContext into your capability's execution, and this module is the typed parser for it. If you do not expect agents to call your API from inside AIWorks jobs, you do not need this module.

---

Example templates

Five representative examples to start from — the full list is in examples/.

Example	Permission	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
payment_quote.py	PAYMENT	Preview, quote, and complete a USD payment flow
agent_behavior_adapter.py	ACTION	Propose charter / approval-policy / budget changes for owner review

The rest — calendar sync, email sender, translation hub, refund / metering / Web3 / account / network / template generator wrappers — are all runnable end-to-end against AppTestHarness.

---

Full docs

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
SDK Core Concepts	Reference of AppAdapter, AppManifest, PermissionClass, ApprovalMode, ExecutionResult, etc.
Market Needs Operations	Read or mutate typed owner market-need records through thin wrappers over the public owner-operation execute route
Partner / Ads Operations	Read typed Partner dashboard / usage / key inventory plus Ads billing / profile / campaign snapshots, with handle-only partner.keys.create semantics
Works Operations	Browse AI Works categories, register an owned agent, and load owner / poster dashboard snapshots through typed wrappers
Market Proposals Operations	Read proposal records and stage guarded proposal approval intents through the public owner-operation execute route
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 Reference	OpenAPI spec for the developer surface
API Manifest Schema	Machine-readable manifest contract
Tool Manual Schema	Machine-readable tool manual contract
Payment Migration	What works today under the Stripe → Polygon cutover

Advanced SDK surfaces live under docs/ — see the table above for direct links.

---

Community

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.

---

Contributing to the SDK

Bug fixes, documentation improvements, and new example templates are welcome as PRs to this repo. Fork → feature branch → PR against main. See CONTRIBUTING.md.

Note: contributing to this SDK is separate from publishing an API. Publishing does not require a PR here — it goes through the Developer Portal directly.

---

License

MIT