Credentials

SDK methods for issuing, updating, revoking, and verifying Sigil credentials.

issueSigil

Creates a new Sigil PDA for the given agent. The client’s wallet acts as the principal and pays for rent.

await client.issueSigil(args: IssueSigilArgs): Promise<TransactionSignature>

IssueSigilArgs

interface IssueSigilArgs {
  agent: PublicKey
  capabilities: Capability[]
  spendLimits: SpendLimits
  expiresAt: number          // unix timestamp in seconds
}

interface Capability {
  category: string           // max 32 bytes
  allowedDomains: string[]   // max 5 entries, 64 bytes each
}

interface SpendLimits {
  perTx:  BN   // max spend per transaction (micro-USDC)
  perDay: BN   // max spend per rolling 24h window (micro-USDC)
}

Example

import BN from 'bn.js'

await client.issueSigil({
  agent: agentPublicKey,
  capabilities: [
    { category: 'image-generation', allowedDomains: ['api.openai.com'] },
    { category: 'web-search',       allowedDomains: [] },
  ],
  spendLimits: {
    perTx:  new BN(100_000),    // 0.1 USDC
    perDay: new BN(5_000_000),  // 5 USDC
  },
  expiresAt: Math.floor(Date.now() / 1000) + 86_400 * 30,
})

---

updateSigil

Updates spend limits and expiry on an existing Sigil. Only the original principal can call this.

await client.updateSigil(args: UpdateSigilArgs): Promise<TransactionSignature>

UpdateSigilArgs

interface UpdateSigilArgs {
  agent: PublicKey
  spendLimits: SpendLimits
  expiresAt: number
}

updateSigil cannot change capabilities. To change what an agent is permitted to do, revoke the existing Sigil and issue a new one.

---

revokeSigil

Permanently marks a Sigil as revoked. The account is not closed. The credential fails all future verifications immediately.

await client.revokeSigil(agent: PublicKey): Promise<TransactionSignature>

Revocation is irreversible. You cannot un-revoke a Sigil.

---

getSigil

Fetches and decodes the on-chain Sigil account for a given agent and principal.

const sigil = await client.getSigil(agent: PublicKey, principal: PublicKey): Promise<SigilAccount>

Throws if the PDA does not exist.

SigilAccount

interface SigilAccount {
  pda: PublicKey
  agentPubkey: PublicKey
  principalPubkey: PublicKey
  capabilities: Capability[]
  spendLimitPerTx: BN
  spendLimitPerDay: BN
  spentToday: BN
  lastReset: BN
  issuedAt: BN
  expiresAt: BN
  revoked: boolean
  bump: number
}

---

getSigilsByPrincipal

Returns all Sigil accounts issued by a given principal. Uses an on-chain memcmp filter — only fetches matching accounts.

const sigils = await client.getSigilsByPrincipal(principal: PublicKey): Promise<SigilAccount[]>

---

verifySigil

Returns true if the agent has a valid Sigil that satisfies the given options. Does not record any spend.

const valid = await client.verifySigil(
  agent: PublicKey,
  options: VerifySigilOptions
): Promise<boolean>

Returns false (never throws) when the account does not exist.

VerifySigilOptions

interface VerifySigilOptions {
  principal: PublicKey         // the principal who issued the Sigil
  requiredCapability?: string  // Sigil must have a capability with this category
  maxSpendAmount?: BN          // spendLimitPerTx must be >= this value
}

---

recordSpend

Records a spend against the agent’s daily limit on-chain.

await client.recordSpend(agent: PublicKey, amount: BN, principal?: PublicKey): Promise<TransactionSignature>

This is called automatically by the x402 middleware. You do not need to call it directly unless you are building custom middleware.

The program rejects the transaction if:

• amount > spendLimitPerTx
• spentToday + amount > spendLimitPerDay (after daily reset if applicable)