io.github.cdonoyan/shuka

Browse the shake-anchored license marketplace. Every offering in the marketplace is anchored to a Shuka shake that proves the underlying rights. Without a license_id this searches offerings; with a license_id it returns full details plus a validation check. Use this to: - Discover license offerings by keyword or brand - Inspect a specific offering before purchasing (purchase_license) - Confirm an offering is real, active, and in good standing

THE DECISION POINT: may this accessor use this data for this purpose right now? Evaluates the stored Terms Layer (status, validity window, remaining uses, purpose binding) AND the shake's revocation state, server-side. Returns a SIGNED verdict. Allowed crossings are receipted and land as ACCESSED events on the hash-chained ledger; a revoked shake denies with consent_revoked. Call this BEFORE acting on data protected by a Shuka proof — it is the same check shuka.guard performs at enterprise enforcement points.

Create a verifiable Shuka attestation for any claim or data. Use this when you need to: - Prove a claim is true with cryptographic certainty - Create an audit trail for data being shared - Attest to compliance, consent, or authorization - Generate a portable proof that other agents can verify Returns a proof token (shk_v1.xxx.yyy) that anyone can verify. Include industry/jurisdiction context directly in the description text — the attestation records the text and optional terms.

Create or retrieve an idempotent Shuka shake. RECOMMENDED for most use cases. The One Ring: Same entity_data always returns the same shake. This is the magic that enables AI agents to repeatedly attest to the same data without creating duplicates - critical for enterprise integrations. This shake is the anchor for EVERYTHING else in the united flow: attach terms (manage_terms), issue a marketplace offering from it (issue_license), and its lifecycle is recorded in the registry (registry). Use this when you need to: - Attest to data that may be referenced multiple times - Create portable proofs that persist across sessions - Ensure billing accuracy (only charged on first creation) - Build reliable audit trails without duplicate entries Returns the shake with was_created=true (new) or was_created=false (existing).

Browse enterprise (multi-seat) license offerings. action="browse": list enterprise offerings (filter by brand, min_seats, max_price). action="acquire": NOT CURRENTLY AVAILABLE — the enterprise seat model is not built yet and the backend returns 501 not_implemented. Use purchase_license for single-grant acquisitions.

Issue a license offering anchored to one of YOUR handshakes (shakes). The united flow: your shake proves the underlying rights; the offering is issued FROM that shake; buyers purchase grants against it; every event is recorded in the append-only registry. Requires an SDK key with license:write permission and an issuer-capable account (Partner/Admin). Get keys at https://shuka.app/dashboard/api-keys Use this to: - Turn an attested asset (voice likeness, IP, dataset rights) into a sellable offering - Set pricing, permitted/prohibited uses, royalties, and grant caps

Look up an existing shake by entity identifiers. Use this to check if a shake already exists before creating a new one, or to retrieve shake details for data you've previously attested. Returns the shake if found, or null if not found.

Manage the rules layer: modifiable terms riding on immutable handshakes. The shake never changes; the terms on it can be amended, re-priced, or revoked WITHOUT re-attesting. This is how user IP stays under the owner's control after attestation. Actions (all require an SDK key assigned to a user; most are billable): - create: attach terms to a handshake (requires handshake_id; access_type defaults to perpetual; 409 terms_exist if the handshake already has terms; needs license:write, $0.05) - get: fetch terms by terms_id - update: amend terms (updates MUST include change_reason or the backend 400s; new revision recorded; needs license:write, $0.03) - revoke: revoke terms (reason is REQUIRED; needs license:write, $0.02) - record_access: log an access under the terms (creates a receipt; purpose must be in permitted_purposes when those are set; needs license:read, $0.01) - revisions: amendment history for terms - receipts: access receipts (audit trail) for terms - by_handshake: get the current terms attached to a handshake

Perform agent-to-agent trust negotiation with Shuka as the arbiter. Use this when: - Another agent presents a proof and you need Shuka to vouch for it - You need a recommendation on whether to proceed with a data exchange - You want detailed validation evidence before trusting external data Returns a recommendation: safe_to_proceed, proceed_with_caution, additional_verification_recommended, or do_not_proceed. NOTE: negotiation is a billable operation (standard shake rate). An invalid proof is rejected by a free pre-check before any charge.

Purchase a license from the marketplace (creates a grant). Returns the transaction, portfolio entry, and the attestation (handshake + proof_token) anchoring the grant to the registry ledger. The proof_token is portable - any agent can verify it with verify_proof. Acquisition is idempotent per buyer+license: a replay returns 409 with no double charge; a license you already own returns 409 already_owned; a payment_amount that doesn't match the current list price returns 400 carrying license_price. Use this to: - Acquire usage rights for an offering found via browse_marketplace - Get a cryptographic proof of your grant for downstream agents

Query the Shuka registry: the append-only ledger and interoperability layer. Actions: - history: full chronological ledger history for an entity (requires entity_type + entity_id) - discover: find registries by industry / shake_type - lookup: look up a registry entity by entity_id - can_issue: check whether an entity can issue a shake type (requires entity_id + shake_type) - will_accept: check whether an entity accepts a shake type from an issuer (requires entity_id + shake_type + issuer_id) - interop_check: full issuer-to-receiver interoperability check (requires issuer_id + receiver_id + shake_type) Use this to trace provenance (every license and grant event is in the ledger) and to confirm two parties can exchange a given shake type BEFORE attempting it.

Revoke a license grant (issuer or admin only). Writes the transactional GRANT_REVOKED event on the grant's ledger chain and revokes the grant's proof token — verify_grant reports it immediately.

Verify a marketplace grant against the append-only registry ledger. Returns the grant status, the anchoring license offering, the attestation, and the integrity of the ledger chain. This is how any agent confirms a grant is real, active, and unrevoked - without trusting the grant holder. Use this when: - Another party claims to hold a license grant - You need to confirm a grant before honoring its permitted uses

Verify a Shuka proof token and get details about the attestation. Use this when you: - Receive a proof token and need to confirm it's valid - Want to check the trust score before proceeding - Need to see what was attested and when - Want to verify claims before acting on data Proof tokens look like: shk_v1.YWJjMTIz.a1b2c3 or ENV-xxx

Verify a shake by its ID and get trust information. Use this to confirm a shake is valid and check its trust score before proceeding with a data exchange.