Agent Integration Guide

Agent identity model

A Soulidity agent is a member record of kind agent, bound to one Sui wallet and registered under a human user's account. Agents authenticate to the API with an API key, and to the Move layer as the holder of SoulGrant objects (or KindPaidEntry rows) issued to their wallet address.

• Web agents (e.g. OpenClaw, Hermes web mode) typically share a wallet with the user's primary account.
• Desktop agents hold their own per-installation wallet and request grants explicitly when first opening a Soul. See Desktop Companion.
• An account's active set is the list of currently-enabled agents under that human user. Auto-grant on append iterates only over the active set.

API key authentication

API keys live on the agent member record and are bcrypt-hashed at rest. They start with the sk- prefix and are shown only during the desktop companion link / rotation flow. Pass them in the Authorization: Bearer <key> header. Endpoints under /api/agent/* require a valid key.

// Use as bearer token
GET /api/agent/souls/search?limit=20
Authorization: Bearer sk-...

// Rotate from the linked desktop companion
POST /api/desktop/me/agent-key/rotate
Authorization: Bearer dtk_...
{ "rotationId": "<client-generated-id>" }

Treat the key as a long-lived secret; rotate on compromise. Lost keys cannot be recovered — only rotated, which invalidates the previously committed key after the desktop flow completes.

Agent endpoints

• GET /api/agent/souls/search
  Search listed Souls visible to agent integrations. Supports q, tag, limit, and offset.
• GET /api/agent/souls/[id]
  Detail for one Soul — includes active grant scopes for this agent, active sprite / audio bindings, and any paid entries.
• GET /api/agent/souls/[id]/access?kind=&name=&versionIndex=
  Agent-authenticated Seal access resolution. Returns approval parameters for the slot — owner, granted-agent, public, or paid-access variant — based on the caller's standing. Defaults to (KIND_SOUL_DOC, "soul", 0) when fields are omitted.
• POST /api/agent/souls/[id]/purchase
  Prepare a listed-Soul purchase for the agent wallet.
• POST /api/agent/souls/[id]/purchase/execute
  Submit the agent signature for a prepared purchase and mirror the successful buy TX.

Supersede semantics

Each Soul has one grant slot per grantee. Issuing a second grant to the same grantee supersedes the first — the new scope_mask fully replaces the old one (no union). This is a behavior change from the early protocol design where issuing a partial scope would silently combine with existing scopes.

The practical consequence: if you (or your tooling) submit a fresh grant TX without first looking up the agent's existing scope, you may unintentionally remove scopes the user already granted. Always pre-check.

grant-merge-masks pre-check

The endpoint below computes existing | added for a list of (soulOnChainId, granteeAddress) pairs. Call it before signing a grant TX that's meant to extend rather than overwrite.

POST /api/souls/grant-merge-masks
{
  "items": [
    {
      "soulOnChainId": "0x...",
      "granteeAddress": "0x...",
      "addedScopeMask": 4    // SCOPE_SKILLS
    }
  ]
}
→ {
  "items": [
    {
      "soulOnChainId": "0x...",
      "granteeAddress": "0x...",
      "addedScopeMask": 4,
      "existingScopeMask": 2,   // pre-existing SCOPE_MEMORY
      "mergedScopeMask": 6,     // memory | skills
      "isNewGrantee": false,
      "currentCapacity": 16,
      "activeGrantCount": 3,
      "requiredCapacity": 16
    }
  ]
}

Use the returned mergedScopeMask and capacity fields to build the actual grant PTB with buildIssueGrantTx or buildBatchIssueGrantsTx. The SDK does not perform this pre-check implicitly; call the endpoint before signing when your intent is to preserve existing scopes.

Auto-grant on append

When a Soul owner uploads a non-public version of any content kind, the web app issues scope-matched SoulGranttop-ups automatically. The rule for each agent in the owner's active set:

1. Read the kind's default_grant_scope_mask from the KindRegistry — call it needed.
2. Read the agent's current grant on this Soul. If the grant's scope_mask & needed == needed, skip — already covered.
3. Otherwise compute merged = existing | needed via grant-merge-masks, then issue a supersede TX with merged.
4. If the supersede TX fails (deploy window race, RPC flake, wallet timeout), Soulidity surfaces a yellow banner on the My Souls detail page enumerating the missing scopes. The owner clicks Retry to catch up.

Agents do not need to do anything to trigger auto-grant — it happens server-side after the owner's append. But agents should treat fresh grant events as the signal to invalidate caches and re-resolve Seal sessions.

Public versions (under public slot_read_mode_mask) are not auto-granted — they are readable without a grant. The auto-grant flow only covers slots whose read mode requires a grant or paid entry.

Failure modes & idempotency

• Ownership rotation race. If a Soul is sold between an agent's grant-check and content fetch, the access call will fail with SEAL_DENIED. The agent should re-query /api/souls/[id] for the new owner and surface a re-authorize prompt to the user.
• Revoke race. Owner revokes mid-conversation: same handling — re-resolve and fail closed to the human.
• Idempotent post-TX mirrors. The Soulidity TX-mirror APIs are keyed on txDigest. Replaying the same digest returns the cached response, so retries are safe.
• Stale paid entries. If an agent enumerates paid entries during a high-throughput rotation, expect some entries to fail the epoch check at Seal time. Treat seal_approve_content_paid_access failures as transient unless three sequential attempts fail.

Web vs desktop agents

Two integration patterns are common:

• Web-hosted agent. Shares the user's primary wallet via the session cookie. Auto-grant on append covers it transparently because the user is also the grantor. Best for hosted SaaS agent products.
• Desktop / sovereign agent. Holds its own wallet and API key. The user authorizes once via a grant TX, then the desktop agent operates independently. Best for local-first persona apps. See Desktop Companion.