Resources

API & SDK Reference

Soulidity exposes REST endpoints for post-TX mirroring, soul browsing, content access, and paid access — plus a TypeScript SDK packaged as @soulidity/sdk for transaction building, on-chain queries, and client-side decryption.

📊 Protocol Stats

REST API — Soul routes

All routes are under /api/souls/ in web/app/api/souls/.

GET/api/souls

Browse all public souls. Supports pagination and tag filters.

GET/api/souls/my

List souls owned by the authenticated user.

GET/api/souls/tags

List popular soul tags with counts.

GET/api/souls/[id]

Get soul detail by on-chain object ID or DB slug.

GET/api/souls/personal-kiosk

Resolve the personal kiosk for the authenticated user's wallet.

POST/api/souls/publish

Mirror a publish TX. Body: txDigest + client-built Seal sidecar object(s) for every initial content slot. Returns soul + state + content mirror.

POST/api/souls/[id]/list

Mirror a fixed-price list TX (atomic USDC).

POST/api/souls/[id]/delist

Mirror a cancel-listing TX.

POST/api/souls/[id]/purchase

Mirror a buy TX (kiosk transfer + fee split).

POST/api/souls/[id]/grant

Mirror a grant issue / revoke / revoke-scope TX. See SoulGrant API.

POST/api/souls/[id]/grant-capacity

Mirror a grant-capacity adjustment TX.

POST/api/souls/grant-merge-masks

Pre-check: body.items[] computes existing | added scope for (soulOnChainId, granteeAddress) pairs and returns capacity planning fields. See Agent Integration.

GET/api/souls/[id]/access

Legacy Soul document access. Resolves only (KIND_SOUL_DOC, 'soul', 0).

GET/api/souls/[id]/content/[kind]/[name]/[versionIndex]/access

Unified Seal access resolution for a specific SoulContent slot. Public plaintext slots can resolve anonymously; sealed slots require auth.

POST/api/souls/[id]/content/sync

Mirror content append/delete/purge/active-binding/state-config TXs. Body includes action, txDigest, kind, name, and sidecar fields as required by the action.

POST/api/souls/[id]/paid-access

Mirror an owner revoke paid-access TX. Body action must be revoke and includes txDigest, buyerAddress, and kind.

REST API — Agent routes

Agent routes are under /api/agent/. Authentication uses an API key in the Authorization: Bearer <key> header. See Agent Integration.

GET/api/agent/souls/search

Search listed Souls visible to agent integrations. Supports q, tag, limit, and offset.

GET/api/agent/souls/[id]

Soul detail visible to the agent — includes active grant state and paid entries for this agent.

GET/api/agent/souls/[id]/access

Resolve a content slot for the authenticated agent. Query params: kind, name, versionIndex.

POST/api/agent/souls/[id]/purchase

Prepare a listed-Soul purchase for the authenticated agent wallet.

POST/api/agent/souls/[id]/purchase/execute

Submit the agent signature for a prepared purchase and mirror the successful buy TX.

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

// Resolve a specific content slot for the agent
GET /api/agent/souls/0x.../access?kind=3&name=memory&versionIndex=0
Authorization: Bearer sk-...

TypeScript SDK structure

The SDK is packaged as @soulidity/sdk (workspace package at packages/soulidity-sdk). Web app code imports from web/lib/soulidity/ which re-exports the package.

File	Purpose
types.ts	All shared TypeScript types: SoulObject, SoulStateObject, SoulContentObject, SoulPaidAccessListObject, SoulGrantScope, access response shapes.
kinds.ts	KIND_* / OP_* / READ_* constants and BUILTIN_KIND_DESCRIPTORS table mirroring kind_registry.move. Single client-side source of truth.
content-document-id.ts	Canonical Seal document-id builder for SoulContent slots. Must match content::assert_matching_document_id byte-for-byte.
content-version-pagination.ts	Cursor pagination over SoulContent versions for browsing memory / skill / sprite history.
queries.ts	On-chain read helpers: getSoulStateObject, getSoulContentObject, getSoulPaidAccessListObject, getSoulGrantObject, getSuccessfulTransactionBlock.
access.ts	resolveContentAccessPayload — owner / granted-agent / paid-access / public Seal access resolution for any SoulContent slot.
events.ts	extractSoulGrantIssuedEvent, ContentVersionAppended, SoulPaidAccessGranted, etc. — parse Move events from TX blocks.
repository.ts	DB query helpers: findSoulAssetDetailByRouteId, toSoulAssetDetail.
server.ts	requireHumanWalletIdentity, assertTransactionSender — server-side auth guards.
personal-kiosk.ts	resolvePersonalKiosk — on-chain kiosk lookup for a wallet address.
tx/publish.ts	buildPublishSoulTx — native mint PTB builder.
tx/personal-join.ts	buildPersonalJoinSoulTx — wrap+link PTB builder.
tx/content.ts	buildAppendContentTx, buildSetActiveBindingTx, buildClearActiveBindingTx, buildDeleteContentVersionTx, buildPurgeContentVersionTx — unified PTBs for every kind.
tx/paid-access.ts	buildConfigureKindPaidAccessTx, buildRecordPurchaseTx, buildAddPaidAccessTx, buildRevokePaidAccessTx — KindPaidConfig + KindPaidEntry PTBs.
tx/mint-helpers.ts	Shared PTB primitives reused by publish / import / personal-join (Walrus blob refs, content envelope serialization).
tx/grant.ts	buildIssueGrantTx, buildBatchIssueGrantsTx, buildRevokeGrantTx, buildBatchRevokeGrantsTx. Use grant-merge-masks first when preserving existing scopes.
tx/buy.ts	buildBuySoulTx — purchase + kiosk transfer PTB.
tx/list.ts, tx/delist.ts, tx/update-price.ts	Fixed-price listing PTBs (atomic USDC).
mirror/	Server-side DB sync helpers — parse-content-sidecars, upsert-content-version, upsert-paid-access, tx-sync.
content-templates.ts	SOUL_MD_TEMPLATE, FOUNDING_MEMORY_MD_TEMPLATE — single source for uploader scaffolds.

Key types

// Scope values
type SoulGrantScope = 'seal' | 'memory' | 'skills' | 'assets'

// Provenance
type SoulProvenanceKind = 'native' | 'imported' | 'personal-join'

// Access responses
type SoulAccessKind = 'owner' | 'granted-agent' | 'paid-access' | 'public'

// Grant lifecycle
type SoulGrantStatus = 'active' | 'revoked' | 'expired' | 'superseded' | 'invalidated'

// SoulState from on-chain (queries.ts) — phase 2 unified content
interface SoulStateObject {
  objectId, packageId, soulId,
  creatorAddress, creatorRoyaltyBps,
  currentOwnerAddress, currentKioskId,
  ownershipEpoch, grantCapacity,
  activeGrantCount,
  activeGrants: ActiveGrantSlotObject[],
  contentId,         // → SoulContent (typed-content root)
  paidAccessListId,  // → SoulPaidAccessList (per-Soul 1:1)
  collectionId,
  isListed,
}

interface ActiveGrantSlotObject {
  grantId, granteeAddress,
  scopeMask: number,
  scopes: SoulGrantScope[],
  expiresAtMs: number | null,
  ownershipEpochSnapshot: number | null,
}

Path aliases

The web app uses these aliases relevant to Soulidity work:

@/* → web/* — local components, hooks, app routes
@web/* → web/* — shared services (Walrus, Seal, Prisma, auth)
@soulidity/sdk → packages/soulidity-sdk — workspace SDK package; re-exported under web/lib/soulidity/

The Prisma client is generated once at generated/prisma/, exposed through src/db/prisma-client.ts, and used from web via @web/lib/prisma. Run npm run prisma:generate after schema changes.

← Back to resources Next: Agent Integration →

Loading…

REST API — Soul routes

All routes are under /api/souls/ in web/app/api/souls/.

GET/api/souls

Browse all public souls. Supports pagination and tag filters.

GET/api/souls/my

List souls owned by the authenticated user.

GET/api/souls/tags

List popular soul tags with counts.

GET/api/souls/[id]

Get soul detail by on-chain object ID or DB slug.

GET/api/souls/personal-kiosk

Resolve the personal kiosk for the authenticated user's wallet.

POST/api/souls/publish

Mirror a publish TX. Body: txDigest + client-built Seal sidecar object(s) for every initial content slot. Returns soul + state + content mirror.

POST/api/souls/[id]/list

Mirror a fixed-price list TX (atomic USDC).

POST/api/souls/[id]/delist

Mirror a cancel-listing TX.

POST/api/souls/[id]/purchase

Mirror a buy TX (kiosk transfer + fee split).

POST/api/souls/[id]/grant

Mirror a grant issue / revoke / revoke-scope TX. See SoulGrant API.

POST/api/souls/[id]/grant-capacity

Mirror a grant-capacity adjustment TX.

POST/api/souls/grant-merge-masks

Pre-check: body.items[] computes existing | added scope for (soulOnChainId, granteeAddress) pairs and returns capacity planning fields. See Agent Integration.

GET/api/souls/[id]/access

Legacy Soul document access. Resolves only (KIND_SOUL_DOC, 'soul', 0).

GET/api/souls/[id]/content/[kind]/[name]/[versionIndex]/access

Unified Seal access resolution for a specific SoulContent slot. Public plaintext slots can resolve anonymously; sealed slots require auth.

POST/api/souls/[id]/content/sync

Mirror content append/delete/purge/active-binding/state-config TXs. Body includes action, txDigest, kind, name, and sidecar fields as required by the action.

POST/api/souls/[id]/paid-access

Mirror an owner revoke paid-access TX. Body action must be revoke and includes txDigest, buyerAddress, and kind.

REST API — Agent routes

Agent routes are under /api/agent/. Authentication uses an API key in the Authorization: Bearer <key> header. See Agent Integration.

GET/api/agent/souls/search

Search listed Souls visible to agent integrations. Supports q, tag, limit, and offset.

GET/api/agent/souls/[id]

Soul detail visible to the agent — includes active grant state and paid entries for this agent.

GET/api/agent/souls/[id]/access

Resolve a content slot for the authenticated agent. Query params: kind, name, versionIndex.

POST/api/agent/souls/[id]/purchase

Prepare a listed-Soul purchase for the authenticated agent wallet.

POST/api/agent/souls/[id]/purchase/execute

Submit the agent signature for a prepared purchase and mirror the successful buy TX.

// Use the desktop-issued agent key as a bearer token GET /api/agent/souls/search?limit=20 Authorization: Bearer sk-... // Resolve a specific content slot for the agent GET /api/agent/souls/0x.../access?kind=3&name=memory&versionIndex=0 Authorization: Bearer sk-...

TypeScript SDK structure

The SDK is packaged as @soulidity/sdk (workspace package at packages/soulidity-sdk). Web app code imports from web/lib/soulidity/ which re-exports the package.

File	Purpose
types.ts	All shared TypeScript types: SoulObject, SoulStateObject, SoulContentObject, SoulPaidAccessListObject, SoulGrantScope, access response shapes.
kinds.ts	KIND_* / OP_* / READ_* constants and BUILTIN_KIND_DESCRIPTORS table mirroring kind_registry.move. Single client-side source of truth.
content-document-id.ts	Canonical Seal document-id builder for SoulContent slots. Must match content::assert_matching_document_id byte-for-byte.
content-version-pagination.ts	Cursor pagination over SoulContent versions for browsing memory / skill / sprite history.
queries.ts	On-chain read helpers: getSoulStateObject, getSoulContentObject, getSoulPaidAccessListObject, getSoulGrantObject, getSuccessfulTransactionBlock.
access.ts	resolveContentAccessPayload — owner / granted-agent / paid-access / public Seal access resolution for any SoulContent slot.
events.ts	extractSoulGrantIssuedEvent, ContentVersionAppended, SoulPaidAccessGranted, etc. — parse Move events from TX blocks.
repository.ts	DB query helpers: findSoulAssetDetailByRouteId, toSoulAssetDetail.
server.ts	requireHumanWalletIdentity, assertTransactionSender — server-side auth guards.
personal-kiosk.ts	resolvePersonalKiosk — on-chain kiosk lookup for a wallet address.
tx/publish.ts	buildPublishSoulTx — native mint PTB builder.
tx/personal-join.ts	buildPersonalJoinSoulTx — wrap+link PTB builder.
tx/content.ts	buildAppendContentTx, buildSetActiveBindingTx, buildClearActiveBindingTx, buildDeleteContentVersionTx, buildPurgeContentVersionTx — unified PTBs for every kind.
tx/paid-access.ts	buildConfigureKindPaidAccessTx, buildRecordPurchaseTx, buildAddPaidAccessTx, buildRevokePaidAccessTx — KindPaidConfig + KindPaidEntry PTBs.
tx/mint-helpers.ts	Shared PTB primitives reused by publish / import / personal-join (Walrus blob refs, content envelope serialization).
tx/grant.ts	buildIssueGrantTx, buildBatchIssueGrantsTx, buildRevokeGrantTx, buildBatchRevokeGrantsTx. Use grant-merge-masks first when preserving existing scopes.
tx/buy.ts	buildBuySoulTx — purchase + kiosk transfer PTB.
tx/list.ts, tx/delist.ts, tx/update-price.ts	Fixed-price listing PTBs (atomic USDC).
mirror/	Server-side DB sync helpers — parse-content-sidecars, upsert-content-version, upsert-paid-access, tx-sync.
content-templates.ts	SOUL_MD_TEMPLATE, FOUNDING_MEMORY_MD_TEMPLATE — single source for uploader scaffolds.

Key types

// Scope values type SoulGrantScope = 'seal' | 'memory' | 'skills' | 'assets' // Provenance type SoulProvenanceKind = 'native' | 'imported' | 'personal-join' // Access responses type SoulAccessKind = 'owner' | 'granted-agent' | 'paid-access' | 'public' // Grant lifecycle type SoulGrantStatus = 'active' | 'revoked' | 'expired' | 'superseded' | 'invalidated' // SoulState from on-chain (queries.ts) — phase 2 unified content interface SoulStateObject { objectId, packageId, soulId, creatorAddress, creatorRoyaltyBps, currentOwnerAddress, currentKioskId, ownershipEpoch, grantCapacity, activeGrantCount, activeGrants: ActiveGrantSlotObject[], contentId, // → SoulContent (typed-content root) paidAccessListId, // → SoulPaidAccessList (per-Soul 1:1) collectionId, isListed, } interface ActiveGrantSlotObject { grantId, granteeAddress, scopeMask: number, scopes: SoulGrantScope[], expiresAtMs: number | null, ownershipEpochSnapshot: number | null, }

Path aliases

The web app uses these aliases relevant to Soulidity work:

@/* → web/* — local components, hooks, app routes

@web/* → web/* — shared services (Walrus, Seal, Prisma, auth)

@soulidity/sdk → packages/soulidity-sdk — workspace SDK package; re-exported under web/lib/soulidity/

The Prisma client is generated once at generated/prisma/, exposed through src/db/prisma-client.ts, and used from web via @web/lib/prisma. Run npm run prisma:generate after schema changes.