> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifier walkthrough

> Seal, deliver, track and revoke KYC records as the verifier.

The tool calls the bank's [KYC inbox](https://docs.trusset.org/endpoints/kyc-inbox/introduction.md) for you. To build the envelope in your own system instead, that page has the format.

**1. Create the signing key**

```bash theme={null}
export TRUSSET_KYC_PASSPHRASE='a long passphrase'
trusset-kyc source-keygen
```

```
Signing key created.
Public key:  c201dc3ced8549ad4e07400a868d9fd043a8d316e7141989c33e8f2f5f844fd6
Fingerprint: 4b37 6734 b088 268b 89d3 cf6d 1a88 0a1c
Stored in:   /srv/kyc/.trusset-kyc/signing-key.json (encrypted with the passphrase)
Send the public key to the bank and confirm the fingerprint with them over a separate channel.
```

Send the public key to the bank. A keystore holds one signing key, and the command refuses to overwrite it. Back up the key file and the passphrase.

**2. Store the invite**

The bank registers your key and gives you an invite string over a confidential channel. The invite comes through Trusset, so the key in it proves nothing on its own. Call the bank over a channel that does not run through Trusset, for example by phone, and have them read you the fingerprint of their recipient key from `trusset-kyc key show` on their machine. Never take it from the invite or from anything Trusset serves. Read them the fingerprint of your signing key in the same call. Then store the invite with the bank's fingerprint:

```bash theme={null}
trusset-kyc invite add 'trusset-kyc-invite:v1:eyJ2IjoxLCJhcGkiOiJodHRwczovL2FwaS50cnVzc2V0Lm9yZyIsInNvdXJjZUlkIjoi...' \
  --fingerprint 'b961 9d9b e69e d903 c31c 6f1a f3c6 a7d2'
```

```
Invite stored for source cmhw2a6r10003l80c9d4h1n8v (Hanse Haftungsdach GmbH).
Bank instance type:        DEVELOPMENT
Profile key:               PROFESSIONAL
API:                       https://api.trusset.org
Recipient key id:          b9619d9be69ed903
Recipient key fingerprint: b961 9d9b e69e d903 c31c 6f1a f3c6 a7d2 (matches the fingerprint the bank gave you)
The inbox reports the same recipient key.
```

The command first checks that the recipient key in the invite has exactly this fingerprint. If it does not, it stores nothing and exits with 2: do not use that invite, it may carry a key that is not the bank's. If it does, it stores the invite and asks the inbox for the bank's key as a consistency check. Spaces and case in the fingerprint do not matter. Without `--fingerprint` nothing is stored.

`invite list` shows stored invites without the token, and the recipient key, its key ID and its fingerprint only for a confirmed invite. A new invite for a source you already stored replaces the old one only with `--replace`, and needs the bank's fingerprint as well.

Invites stored by version 1.1.0 or earlier were never checked against the bank's fingerprint, and `seal` and `send` refuse them. Confirm each with `trusset-kyc invite confirm --source <sourceId> --fingerprint '<fingerprint the bank read out>'`. A wrong fingerprint leaves the invite stored but not confirmed.

**3. Seal a record**

```bash theme={null}
trusset-kyc seal --source cmhw2a6r10003l80c9d4h1n8v \
  --wallet 0x8ba1f109551bD432803012645Ac136ddd64DBA72 \
  --record customer.json \
  --attach id-front.jpg --attach proof-of-address.pdf \
  --verified-at 2026-11-10 --valid-until 2027-11-10
```

```
Sealed for recipient key b9619d9be69ed903 (b961 9d9b e69e d903 c31c 6f1a f3c6 a7d2).
Envelope id:   75aa6ca04ca5ab4223136c3bea128de0
Record digest: 565dd632e69c3630319efbd08052d5fd1dfbdd5b1123b31e227502261fae5b9d
Sealed size:   240932 bytes
Written to:    /srv/kyc/75aa6ca04ca5ab4223136c3bea128de0.envelope.json
Send it within 24 hours with: trusset-kyc send /srv/kyc/75aa6ca04ca5ab4223136c3bea128de0.envelope.json
```

Sealing works offline. It writes `<envelopeId>.envelope.json`, which holds the delivery body: the clear header, the encapsulated key, the ciphertext and your signature. It contains no key and no plaintext. `--out <file>` chooses another name, and an existing file is never overwritten.

Keep the record digest. A revocation names the record by it.

**4. Send it**

```bash theme={null}
trusset-kyc send 75aa6ca04ca5ab4223136c3bea128de0.envelope.json
```

```
Delivered.
Record id:   cmhw3k9t20007l80c5q2x7m4d
Status:      RECEIVED
Received at: 2026-11-12T09:14:09.204Z
```

Before it sends, the tool asks the inbox for the bank's key again. If that key differs from the key your invite pins, or the envelope is sealed to another key ID, it sends nothing and tells you the bank must issue a new invite. `seal --send` seals and sends in one step with the same check.

An envelope must be sent within 24 hours of sealing. Sending the same envelope twice is safe: the second call returns the same record and stores nothing new.

**5. Follow the record**

```bash theme={null}
trusset-kyc status --source cmhw2a6r10003l80c9d4h1n8v 75aa6ca04ca5ab4223136c3bea128de0
```

It prints the fields of [Get Delivery Status](https://docs.trusset.org/endpoints/kyc-inbox/get-delivery-status.md): the status, when the bank opened, approved or rejected the record, the reject reason, and whether the wallet is admitted.

## The record file

The file given to `--record` is a JSON object. Its content is free: the tool does not interpret it, and Trusset never sees it. Agree the fields with the bank. For example:

```json theme={null}
{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "dateOfBirth": "1990-12-10",
  "nationality": "GB",
  "address": { "street": "12 Analytical Row", "postalCode": "N1 9GU", "city": "London", "country": "GB" },
  "documentType": "PASSPORT",
  "documentNumber": "X1234567",
  "documentExpiry": "2031-05-01",
  "verificationMethod": "VIDEO_IDENT",
  "verificationReference": "HH-2026-000123",
  "pepSanctionsResult": "CLEAR"
}
```

Attachments are files of any type, added with one `--attach` each. A name must be a plain file name of at most 120 characters, without a path separator or a leading dot, and unique within the record in any letter case.

The whole sealed record, attachments included, may be at most 6 MiB (6,291,456 bytes). Attachments are base64 encoded inside the record, so about 4.5 MiB of files fit. `seal` refuses a larger record and states its size.

## Dates

`--valid-until` is required. `--verified-at` defaults to the current time. Both take a full timestamp such as `2026-11-10T09:30:00.000Z` or a date. A date given as `YYYY-MM-DD` means the start of that day in UTC for `--verified-at` and the end of that day in UTC for `--valid-until`.

`validUntil` is the date until which you vouch for the record. When it passes, the record expires at the bank and the bank is asked to remove the wallet from its whitelists.

## Revoke a record

```bash theme={null}
trusset-kyc revoke --source cmhw2a6r10003l80c9d4h1n8v \
  --wallet 0x8ba1f109551bD432803012645Ac136ddd64DBA72 \
  --digest 565dd632e69c3630319efbd08052d5fd1dfbdd5b1123b31e227502261fae5b9d \
  --reason WITHDRAWN
```

```
Revoked.
Record id:  cmhw3k9t20007l80c5q2x7m4d
Status:     REVOKED
Revoked at: 2027-02-03T08:40:13.027Z
```

Reasons are `EXPIRED`, `WITHDRAWN`, `SUPERSEDED`, `INVALID` and `OTHER`. The tool signs the revocation with your signing key.

> [!WARNING]
>
> A revocation changes the record at the bank and notifies the bank. It removes nothing on chain: a wallet the bank already listed stays listed until the bank's own wallet signs the removal. See [Revoke Record](https://docs.trusset.org/endpoints/kyc-inbox/revoke-record.md).

## When the bank replaces its key

`send` then refuses with a message that the reported key differs from the pinned one. Ask the bank for a new invite and for the fingerprint of its new key from `trusset-kyc key show`, store the invite with `invite add --replace --fingerprint '<new fingerprint>'`, and seal the waiting records again. An envelope sealed to the old key cannot be delivered.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.