Loading…
Resources
Soulidity exposes REST API endpoints for post-TX mirroring, soul browsing, and access resolution — plus a TypeScript SDK in web/lib/soulidity/ for transaction building, on-chain queries, and client-side decryption.
All routes are under /api/souls/ in web/app/api/souls/.
/api/soulsBrowse all public souls. Supports pagination and tag filters.
/api/souls/myList souls owned by the authenticated user.
/api/souls/tagsList popular soul tags with counts.
/api/souls/[id]Get soul detail by on-chain object ID or DB slug.
/api/souls/publishMirror a publish TX. Body: txDigest + client-built Seal sidecar object(s). Returns soul + state mirror.
/api/souls/[id]/metadataMirror a SoulMetadata binding/blob mutation TX and refresh the mirrored metadata projection.
/api/souls/personal-kioskResolve the personal kiosk for the authenticated user's wallet.
/api/souls/[id]/grantMirror a grant issue/revoke TX. See SoulGrant API docs.
/api/souls/[id]/memory/[entryKey]/accessResolve Seal access params for a memory entry.
/api/souls/[id]/skills/[skillName]/versions/[versionIndex]/accessResolve Seal access params for a private skill version.
Agent-specific routes are under /api/agent/ in web/app/api/agent/. Authentication uses an API key in the Authorization: Bearer <key> header.
/api/agent/api-keyGenerate or rotate an API key for an agent member. Requires human auth and ownership of the agent account. Rate-limited to 1 rotation/hour per agent.
/api/agent/soulsSearch and list souls accessible to the authenticated agent.
/api/agent/souls/[id]Get soul detail visible to the agent (includes active grant state).
// Generate API key (human-authenticated)
POST /api/agent/api-key
{ "agentMemberId": "<uuid>" }
→ { "apiKey": "snk_..." }
// Use API key as bearer token
GET /api/agent/souls
Authorization: Bearer snk_...All SDK files live in web/lib/soulidity/.
| File | Purpose |
|---|---|
| types.ts | All shared TypeScript types: SoulObject, SoulStateObject, SoulGrantScope, access response shapes, etc. |
| queries.ts | On-chain read helpers: getSoulStateObject, getSoulGrantObject, getSuccessfulTransactionBlock. |
| access.ts | resolveSoulAccessPayload — owner vs granted-agent Seal access resolution for Soul content. |
| memory-access.ts | resolveMemoryAccessPayload — same pattern for memory entry access. |
| skill-access.ts | fetchSkillAccess + loadDecryptedPrivateSkillVersion — full client-side decryption flow for private skills. |
| events.ts | extractSoulGrantIssuedEvent, extractSoulGrantRevokedEvent, 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/metadata.ts | buildSetActiveSpriteTx, buildClearActiveSpriteTx, buildSetActiveVoiceTx, buildUpsertMetadataBlobTx — owner SoulMetadata maintenance PTBs. |
| tx/grant.ts | buildIssueSoulGrantTx, buildRevokeSoulGrantTx. |
| tx/buy.ts | buildBuySoulTx — purchase + kiosk transfer PTB. |
| tx/memory.ts | buildAppendMemoryTx — append memory entry PTB. |
| tx/skills.ts | buildAppendSkillVersionTx, buildDeleteSkillVersionTx. |
| mirror/ | Server-side DB sync helpers — sync-helpers.ts, build-seal-sidecars.ts, tx-sync.ts. |
// Scope values
type SoulGrantScope = 'seal' | 'memory' | 'skills' | 'assets'
// Provenance
type SoulProvenanceKind = 'native' | 'imported' | 'personal-join'
// Access responses
type SoulAccessKind = 'owner' | 'granted-agent'
// Grant lifecycle
type SoulGrantStatus = 'active' | 'revoked' | 'expired' | 'superseded' | 'invalidated'
// SoulState from on-chain (queries.ts)
interface SoulStateObject {
objectId, packageId, soulId,
creatorAddress, creatorRoyaltyBps,
currentOwnerAddress, currentKioskId,
ownershipEpoch, grantCapacity,
activeGrantCount,
activeGrants: ActiveGrantSlotObject[],
memoryId, metadataId, skillsId, collectionId,
}
interface ActiveGrantSlotObject {
grantId, granteeAddress,
scopeMask: number,
scopes: SoulGrantScope[],
expiresAtMs: number | null,
}web uses two aliases relevant to Soulidity work:
@/* → web/* — local SDK, components, hooks@web/* → web/* — shared services (Walrus, Seal, Prisma, auth)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.