> ## Documentation Index
> Fetch the complete documentation index at: https://sigil-10dddbf2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts theme={null}
await client.issueSigil(args: IssueSigilArgs): Promise<TransactionSignature>
```

### IssueSigilArgs

```ts theme={null}
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

```ts theme={null}
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.

```ts theme={null}
await client.updateSigil(args: UpdateSigilArgs): Promise<TransactionSignature>
```

### UpdateSigilArgs

```ts theme={null}
interface UpdateSigilArgs {
  agent: PublicKey
  spendLimits: SpendLimits
  expiresAt: number
}
```

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

***

## revokeSigil

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

```ts theme={null}
await client.revokeSigil(agent: PublicKey): Promise<TransactionSignature>
```

<Warning>
  Revocation is irreversible. You cannot un-revoke a Sigil.
</Warning>

***

## getSigil

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

```ts theme={null}
const sigil = await client.getSigil(agent: PublicKey, principal: PublicKey): Promise<SigilAccount>
```

Throws if the PDA does not exist.

### SigilAccount

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
const valid = await client.verifySigil(
  agent: PublicKey,
  options: VerifySigilOptions
): Promise<boolean>
```

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

### VerifySigilOptions

```ts theme={null}
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.

```ts theme={null}
await client.recordSpend(agent: PublicKey, amount: BN, principal?: PublicKey): Promise<TransactionSignature>
```

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

The program rejects the transaction if:

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