API Reference

Claim Types

Claims are JSON objects that specify what information or action you need from the user's wallet. They form the core of any DID Connect request. You define an array of claims when setting up your endpoints with WalletHandlers to create a customized authentication workflow, from a simple sign-in to complex actions like presenting credentials or signing transactions.
This guide provides a comprehensive reference for each available claim type, including its purpose, properties, validation rules, and usage examples. For details on how to use these claims in your application, see the WalletHandlers Class documentation.
Summary of Claim Types#Here is a quick overview of the available claims you can request from a user's wallet.
Claim Type
Description
authPrincipal
Asks the user to select a wallet account for authentication.
profile
Requests personal information from the user's wallet profile.
verifiableCredential
Requests a specific Verifiable Credential (VC) that meets certain criteria.
asset
Requests a specific digital asset, such as an NFT.
assetOrVC
Requests either a Verifiable Credential or a digital asset.
signature
Asks the user to sign a message or transaction hash.
prepareTx
Asks the user to review and sign a transaction prepared by the application.
agreement
Asks the user to confirm their agreement to a document, such as a Terms of Service.
keyPair
Asks the user to create a new account in their wallet for your application.
encryptionKey
Asks the wallet to derive an encryption key for secure data exchange.

authPrincipal#Use this claim to ask the user to select one of their existing accounts to proceed. This is the most common and basic form of authentication, typically used as the first step in any workflow.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"authPrincipal"
The type of the claim. Must be authPrincipal.
description
string
No
"Please continue with your account"
A message displayed to the user in their wallet.
target
string
No
""
Optional. Suggest a specific DID for the user to select.
supervised
boolean
No
false
If true, indicates the session may be supervised, which can alter wallet behavior.
targetType
object
No
{...}
Specifies the required cryptographic properties (key, hash, role, encoding) of the selected account.
Example Usage
// In your WalletHandlers configuration
const claims = [
  {
    type: 'authPrincipal',
    description: 'Sign in to My Awesome App'
  }
];
profile#Requests personal information from the user's wallet profile. The user will be prompted to approve or deny sharing for each requested item.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"profile"
The type of the claim. Must be profile.
description
string
No
"Please provide your profile to continue."
A message displayed to the user.
items
string[]
No
['fullName']
An array of profile fields to request. Valid items: did, fullName, email, phone, signature, avatar, birthday, url.
Example Usage
// Request the user's full name and email after they sign in
const claims = [
  { type: 'authPrincipal' },
  {
    type: 'profile',
    description: 'We need your name and email to create your account.',
    items: ['fullName', 'email']
  }
];
verifiableCredential#Requests the user to present a Verifiable Credential (VC) that meets specific criteria. You can filter by type, issuer, and other properties. This is useful for proving qualifications, membership, or identity.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"verifiableCredential"
The type of the claim.
description
string
No
"Please present a verifiable credential..."
A message displayed to the user.
optional
boolean
No
false
If true, the user can skip this step without failing the flow.
filters
object[]
No
undefined
An array of filter objects. The wallet finds VCs matching any (OR) of these filters. Properties inside a filter are combined with AND.
acquireUrl
string
No
""
A URL where the user can obtain the credential if they don't have it.
Filter Object Properties
Property
Type
Description
type
string[]
An array of acceptable VC types (e.g., ["VerifiableCredential", "ProofOfPersonhood"]).
trustedIssuers
`(string
object)[]`
target
string
The DID of the VC itself.
tag
string
A specific tag associated with the VC.
Example Usage
// Request a developer certificate from a specific issuer
const claims = [
  {
    type: 'verifiableCredential',
    description: 'Please present your Developer Certificate to access the beta.',
    filters: [{
      type: ['DeveloperCertificate'],
      trustedIssuers: ['did:abt:z1issuerdid...']
    }],
    acquireUrl: 'https://example.com/get-developer-cert'
  }
];
asset#Requests the user to present a digital asset (like an NFT) that meets specific criteria. This can be used for token-gated access, ownership verification, or using an asset in-app.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"asset"
The type of the claim.
description
string
No
"Please present an on chain asset..."
A message displayed to the user.
optional
boolean
No
false
If true, the user can skip this step.
filters
object[]
No
undefined
An array of filter objects. The wallet finds assets matching any (OR) of these filters.
acquireUrl
string
No
""
A URL where the user can obtain the asset if they don't have it.
Filter Object Properties
Property
Type
Description
address
string
The DID address of the asset itself.
trustedIssuers
`(string
object)[]`
trustedParents
string[]
An array of DIDs of trusted parent assets (e.g., the NFT contract address).
tag
string
A specific tag associated with the asset.
consumed
boolean
If true, requests an unconsumed asset. If false, a consumed one. If omitted, either is accepted.
Example Usage
// Request an NFT from a specific collection (factory) for a discount
const claims = [
  {
    type: 'asset',
    description: 'Show your Early Supporter NFT to get a discount.',
    filters: [{
      trustedParents: ['did:abt:z1nftfactorydid...']
    }]
  }
];
assetOrVC#Requests the user to present either a digital asset or a Verifiable Credential that meets the specified criteria. This provides flexibility when access can be granted by multiple token types.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"assetOrVC"
The type of the claim.
description
string
No
"Please present NFT to continue."
A message displayed to the user.
optional
boolean
No
false
If true, the user can skip this step.
filters
object[]
Yes
N/A
An array of filter objects. The wallet finds items matching any (OR) filter. Filters can contain properties for both assets and VCs.
Example Usage
// Request either a VIP Pass NFT or a VIP Pass Credential to enter
const claims = [
  {
    type: 'assetOrVC',
    description: 'Present your VIP pass (NFT or Certificate) to enter.',
    filters: [
      // Option 1: The VIP Pass NFT
      {
        trustedParents: ['did:abt:z1vipnftfactorydid...']
      },
      // Option 2: The VIP Pass VC
      {
        type: ['VipPassCredential'],
        trustedIssuers: ['did:abt:z1vipissuerdid...']
      }
    ]
  }
];
signature#Requests the user to sign a piece of data. This can be used to prove control over a DID, authorize an off-chain action, or sign a transaction for another blockchain.
Properties
Property
Type
Required
Default
Description
typeUrl
string
Yes
N/A
Specifies the data type being signed. Valid values: fg:t:transaction, mime:text/plain, eth:typed-data, and more.
description
string
No
"Sign this transaction or message..."
A message displayed to the user.
display
string
No
""
A human-readable representation of the data to be signed. If blank, wallet may show the raw data.
method
string
No
"sha3"
Hashing method. Can be none if data is already a hash.
digest
string
No
""
The pre-computed hash of the original data. If provided, the wallet will not re-hash.
origin
string
No
""
The origin of the request, typically the application's URL.
requirement
object
No
undefined
An object specifying token or asset requirements needed to perform the signature.
Example Usage
// Request a signature on a simple text message
const claims = [
  {
    type: 'signature',
    description: 'Sign this message to confirm your action.',
    typeUrl: 'mime:text/plain',
    display: 'I agree to the terms and conditions outlined at example.com/tos',
    origin: 'https://yourapp.com'
  }
];
prepareTx#Requests the user to sign a transaction that has been partially prepared by the application. This is common for on-chain interactions where the application constructs the transaction payload and the wallet only needs to sign and broadcast it.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"prepareTx"
The type of the claim.
description
string
No
"Prepare and sign this transaction..."
A message displayed to the user.
partialTx
string
Yes
N/A
The serialized partial transaction string for the wallet to process.
display
string
No
""
A human-readable representation of the transaction's purpose.
requirement
object
Yes
N/A
An object specifying token requirements (e.g., for gas fees) needed to perform the transaction.
Example Usage
// Request a signature for a pre-built transaction
const claims = [
  {
    type: 'prepareTx',
    description: 'Confirm your on-chain registration.',
    partialTx: '{\"itx\":{\"nonce\":0,...}}', // Serialized transaction data
    display: JSON.stringify({ action: 'Register', fee: '0.1 ABT' }),
    requirement: {
      tokens: [{
        address: 'did:abt:z1T_fA7fB3eC4pA-E3eC4p_A7fB3eC4p',
        value: '100000000000000000' // 0.1 ABT in rock
      }]
    }
  }
];
agreement#Requests the user to confirm their agreement to a document, such as a Terms of Service or Privacy Policy. The wallet verifies that the hash of the document at the given URI matches the provided digest.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"agreement"
The type of the claim.
description
string
No
"Confirm your agreement to continue."
A message displayed to the user.
uri
string
Yes
N/A
The URL of the document for the user to review.
method
string
No
"sha2"
The hashing algorithm used to create the digest.
digest
string
Yes
N/A
The hash of the document content at the URI.
Example Usage
// Request user to agree to the Terms of Service
const claims = [
  {
    type: 'agreement',
    description: 'Please agree to our Terms of Service to continue.',
    uri: 'https://example.com/terms-of-service.txt',
    method: 'sha256',
    digest: 'f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2'
  }
];
keyPair#Requests the user to create a new account (key pair) in their wallet. This is useful for applications that need to provision a dedicated DID for a user without requiring them to leave the app.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"keyPair"
The type of the claim.
description
string
No
"Please create account to continue."
A message displayed to the user.
moniker
string
Yes
N/A
A nickname for the new account, which will be visible in the user's wallet.
declare
boolean
No
true
If true, the wallet will attempt to declare the new DID on-chain.
migrateFrom
string
No
""
Optional. If provided, indicates this new key should replace an old one.
targetType
object
No
{...}
Specifies the required cryptographic properties of the new account.
Example Usage
// Ask the user to create a new, dedicated account for the game
const claims = [
  {
    type: 'keyPair',
    description: 'Create a game character account.',
    moniker: 'MyGameCharacter'
  }
];
encryptionKey#Requests the wallet to derive a deterministic encryption key from the user's secret key and a provided salt. This enables secure communication between the application and the wallet without exposing the user's main private key. See the Enable Secure Mode guide for a detailed walkthrough.
Properties
Property
Type
Required
Default
Description
type
string
Yes
"encryptionKey"
The type of the claim.
description
string
No
"Please provide encryptionKey..."
A message displayed to the user.
salt
string
Yes
N/A
A public, unique string used for key derivation. A session or action ID is a good choice.
delegation
string
No
""
Optional. A DID or JWT for delegation scenarios.
Example Usage
// Request an encryption key to secure a subsequent 'keyPair' response
const claims = [
  {
    type: 'encryptionKey',
    description: 'Enable secure mode to protect your new key.',
    salt: 'unique-session-id-12345'
  },
  {
    type: 'keyPair',
    moniker: 'MyNewSecureAccount'
  }
];

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"authPrincipal"`	The type of the claim. Must be `authPrincipal`.
`description`	`string`	No	`"Please continue with your account"`	A message displayed to the user in their wallet.
`target`	`string`	No	`""`	Optional. Suggest a specific DID for the user to select.
`supervised`	`boolean`	No	`false`	If `true`, indicates the session may be supervised, which can alter wallet behavior.
`targetType`	`object`	No	`{...}`	Specifies the required cryptographic properties (key, hash, role, encoding) of the selected account.

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"profile"`	The type of the claim. Must be `profile`.
`description`	`string`	No	`"Please provide your profile to continue."`	A message displayed to the user.
`items`	`string[]`	No	`['fullName']`	An array of profile fields to request. Valid items: `did`, `fullName`, `email`, `phone`, `signature`, `avatar`, `birthday`, `url`.

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"verifiableCredential"`	The type of the claim.
`description`	`string`	No	`"Please present a verifiable credential..."`	A message displayed to the user.
`optional`	`boolean`	No	`false`	If `true`, the user can skip this step without failing the flow.
`filters`	`object[]`	No	`undefined`	An array of filter objects. The wallet finds VCs matching any (`OR`) of these filters. Properties inside a filter are combined with `AND`.
`acquireUrl`	`string`	No	`""`	A URL where the user can obtain the credential if they don't have it.

Property	Type	Description
`type`	`string[]`	An array of acceptable VC types (e.g., `["VerifiableCredential", "ProofOfPersonhood"]`).
`trustedIssuers`	`(string	object)[]`
`target`	`string`	The DID of the VC itself.
`tag`	`string`	A specific tag associated with the VC.

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"asset"`	The type of the claim.
`description`	`string`	No	`"Please present an on chain asset..."`	A message displayed to the user.
`optional`	`boolean`	No	`false`	If `true`, the user can skip this step.
`filters`	`object[]`	No	`undefined`	An array of filter objects. The wallet finds assets matching any (`OR`) of these filters.
`acquireUrl`	`string`	No	`""`	A URL where the user can obtain the asset if they don't have it.

Overview

Getting Started

Core Concepts

How-to Guides

API Reference

Advanced Topics

Claim Types

Summary of Claim Types#

`authPrincipal`#

`profile`#

`verifiableCredential`#

`asset`#

`assetOrVC`#

`signature`#

`prepareTx`#

`agreement`#

`keyPair`#

`encryptionKey`#

Configuration Objects

Advanced Topics

Claim Type	Description
`authPrincipal`	Asks the user to select a wallet account for authentication.
`profile`	Requests personal information from the user's wallet profile.
`verifiableCredential`	Requests a specific Verifiable Credential (VC) that meets certain criteria.
`asset`	Requests a specific digital asset, such as an NFT.
`assetOrVC`	Requests either a Verifiable Credential or a digital asset.
`signature`	Asks the user to sign a message or transaction hash.
`prepareTx`	Asks the user to review and sign a transaction prepared by the application.
`agreement`	Asks the user to confirm their agreement to a document, such as a Terms of Service.
`keyPair`	Asks the user to create a new account in their wallet for your application.
`encryptionKey`	Asks the wallet to derive an encryption key for secure data exchange.

Property	Type	Description
`address`	`string`	The DID address of the asset itself.
`trustedIssuers`	`(string	object)[]`
`trustedParents`	`string[]`	An array of DIDs of trusted parent assets (e.g., the NFT contract address).
`tag`	`string`	A specific tag associated with the asset.
`consumed`	`boolean`	If `true`, requests an unconsumed asset. If `false`, a consumed one. If omitted, either is accepted.

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"assetOrVC"`	The type of the claim.
`description`	`string`	No	`"Please present NFT to continue."`	A message displayed to the user.
`optional`	`boolean`	No	`false`	If `true`, the user can skip this step.
`filters`	`object[]`	Yes	N/A	An array of filter objects. The wallet finds items matching any (`OR`) filter. Filters can contain properties for both assets and VCs.

Property	Type	Required	Default	Description
`typeUrl`	`string`	Yes	N/A	Specifies the data type being signed. Valid values: `fg:t:transaction`, `mime:text/plain`, `eth:typed-data`, and more.
`description`	`string`	No	`"Sign this transaction or message..."`	A message displayed to the user.
`display`	`string`	No	`""`	A human-readable representation of the data to be signed. If blank, wallet may show the raw data.
`method`	`string`	No	`"sha3"`	Hashing method. Can be `none` if data is already a hash.
`digest`	`string`	No	`""`	The pre-computed hash of the original data. If provided, the wallet will not re-hash.
`origin`	`string`	No	`""`	The origin of the request, typically the application's URL.
`requirement`	`object`	No	`undefined`	An object specifying token or asset requirements needed to perform the signature.

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"prepareTx"`	The type of the claim.
`description`	`string`	No	`"Prepare and sign this transaction..."`	A message displayed to the user.
`partialTx`	`string`	Yes	N/A	The serialized partial transaction string for the wallet to process.
`display`	`string`	No	`""`	A human-readable representation of the transaction's purpose.
`requirement`	`object`	Yes	N/A	An object specifying token requirements (e.g., for gas fees) needed to perform the transaction.

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"agreement"`	The type of the claim.
`description`	`string`	No	`"Confirm your agreement to continue."`	A message displayed to the user.
`uri`	`string`	Yes	N/A	The URL of the document for the user to review.
`method`	`string`	No	`"sha2"`	The hashing algorithm used to create the digest.
`digest`	`string`	Yes	N/A	The hash of the document content at the URI.

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"keyPair"`	The type of the claim.
`description`	`string`	No	`"Please create account to continue."`	A message displayed to the user.
`moniker`	`string`	Yes	N/A	A nickname for the new account, which will be visible in the user's wallet.
`declare`	`boolean`	No	`true`	If `true`, the wallet will attempt to declare the new DID on-chain.
`migrateFrom`	`string`	No	`""`	Optional. If provided, indicates this new key should replace an old one.
`targetType`	`object`	No	`{...}`	Specifies the required cryptographic properties of the new account.

Property	Type	Required	Default	Description
`type`	`string`	Yes	`"encryptionKey"`	The type of the claim.
`description`	`string`	No	`"Please provide encryptionKey..."`	A message displayed to the user.
`salt`	`string`	Yes	N/A	A public, unique string used for key derivation. A session or action ID is a good choice.
`delegation`	`string`	No	`""`	Optional. A DID or JWT for delegation scenarios.