### Run All Example Services

Source: https://github.com/agentcommercekit/ack/blob/main/README.md

Command to start all example services locally.

```sh
pnpm dev:examples
```

--------------------------------

### Setup Identities

Source: https://github.com/agentcommercekit/ack/blob/main/examples/local-did-host/README.md

Generate private keys for each identity.

```sh
pnpm run setup

```

--------------------------------

### Run the Server

Source: https://github.com/agentcommercekit/ack/blob/main/examples/local-did-host/README.md

Start the Hono server.

```sh
pnpm run dev

```

--------------------------------

### Run Verifier Server

Source: https://github.com/agentcommercekit/ack/blob/main/docs/demos/example-verifier.mdx

Starts the Credential Verifier server locally.

```shell
pnpm run dev
```

--------------------------------

### Setup ACK

Source: https://github.com/agentcommercekit/ack/blob/main/README.md

Installs necessary packages and sets up local environment variables for running demos.

```sh
pnpm run setup
```

--------------------------------

### Install Mintlify CLI

Source: https://github.com/agentcommercekit/ack/blob/main/docs/README.md

If Mintlify CLI is not installed globally, run this command.

```sh
pnpm i -g mintlify
```

--------------------------------

### Installation

Source: https://github.com/agentcommercekit/ack/blob/main/packages/did/README.md

Install the @agentcommercekit/did package using npm or pnpm.

```sh
npm i @agentcommercekit/did
# or
pnpm add @agentcommercekit/did
```

--------------------------------

### Installation

Source: https://github.com/agentcommercekit/ack/blob/main/packages/vc/README.md

Install the @agentcommercekit/vc package using npm or pnpm.

```sh
npm i @agentcommercekit/vc
# or
pnpm add @agentcommercekit/vc
```

--------------------------------

### Installation

Source: https://github.com/agentcommercekit/ack/blob/main/packages/keys/README.md

Install the @agentcommercekit/keys package using npm or pnpm.

```sh
npm i @agentcommercekit/keys
# or
pnpm add @agentcommercekit/keys
```

--------------------------------

### Branching Strategy Example

Source: https://github.com/agentcommercekit/ack/blob/main/CONTRIBUTING.md

Example Git commands for creating a new branch for feature or bugfix contributions.

```bash
git checkout -b feature/your-feature-name
git checkout -b bugfix/issue-number
```

--------------------------------

### Clone the Agent Commerce Kit repository

Source: https://github.com/agentcommercekit/ack/blob/main/docs/demos/quickstart.mdx

Clones the ACK repository and navigates into the project directory.

```shell
git clone https://github.com/agentcommercekit/ack.git
cd ack
```

--------------------------------

### Complete did:web Document Example

Source: https://github.com/agentcommercekit/ack/blob/main/docs/demos/demo-identity.mdx

Complete `did:web` Document Example:

```json
{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:web:agent.example.com",
  "verificationMethod": [
    {
      "id": "did:web:agent.example.com#jwk-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:agent.example.com",
      "publicKeyJwk": { "kty": "EC", "crv": "secp256k1" }
    }
  ],
  "controller": "did:key:zQ3shg46zUAV...",
  "service": [
    {
      "id": "did:web:agent.example.com/v1/messages",
      "type": "MessagingEndpoint",
      "serviceEndpoint": "http://agent.example.com/v1/messages"
    },
    {
      "id": "did:web:agent.example.com/identity",
      "type": "IdentityService",
      "serviceEndpoint": "http://agent.example.com/identity"
    }
  ]
}
```

--------------------------------

### Installation using npm or pnpm

Source: https://github.com/agentcommercekit/ack/blob/main/packages/agentcommercekit/README.md

Installs the main agentcommercekit package.

```sh
npm i agentcommercekit
# or
pnpm add agentcommercekit
```

--------------------------------

### Install @agentcommercekit/jwt

Source: https://github.com/agentcommercekit/ack/blob/main/packages/jwt/README.md

Install the package using npm or pnpm.

```sh
npm i @agentcommercekit/jwt
# or
pnpm add @agentcommercekit/jwt
```

--------------------------------

### Schema Validation Examples

Source: https://github.com/agentcommercekit/ack/blob/main/packages/did/README.md

Examples of importing Zod and Valibot schemas for DID URIs.

```ts
// Zod v4 schemas

// Valibot schemas
import { didUriSchema } from "@agentcommercekit/did/schemas/valibot"
// Zod v3 schemas
import { didUriSchema } from "@agentcommercekit/did/schemas/zod/v3"
import { didUriSchema } from "@agentcommercekit/did/schemas/zod/v4"
```

--------------------------------

### Pushing Changes Example

Source: https://github.com/agentcommercekit/ack/blob/main/CONTRIBUTING.md

Example Git command for pushing changes to a remote branch in a fork.

```bash
git push origin feature/your-feature-name
```

--------------------------------

### Creating and Signing a Credential

Source: https://github.com/agentcommercekit/ack/blob/main/packages/vc/README.md

Example of creating and signing a W3C Verifiable Credential using the package.

```ts
import { getDidResolver } from "@agentcommercekit/did"
import { createJwtSigner } from "@agentcommercekit/jwt"
import { generateKeypair } from "@agentcommercekit/keys"
import { createCredential, signCredential } from "@agentcommercekit/vc"

const issuerDid = createDidWebUri("https://issuer.example.com")

// Create credential
const credential = createCredential({
  type: "ExampleCredential",
  issuer: issuerDid,
  subject: "did:example:subject",
  attestation: {
    claim: "value",
  },
})

// Sign credential
const resolver = getDidResolver()
const issuerKeypair = await generateKeypair("secp256k1")
const signer = createJwtSigner(issuerKeypair)

const { jwt, verifiableCredential } = await signCredential(credential, {
  did: issuerDid,
  signer,
  resolver,
})

// jwt - signed credential in jwt form
// verifiableCredential - signed credential object
```

--------------------------------

### Installation

Source: https://github.com/agentcommercekit/ack/blob/main/packages/ack-pay/README.md

Install the ACK-Pay TypeScript SDK using npm or pnpm.

```sh
npm i @agentcommercekit/ack-pay
# or
pnpm add @agentcommercekit/ack-pay
```

--------------------------------

### Sample cURL for Creating Payment Receipt Credential

Source: https://github.com/agentcommercekit/ack/blob/main/examples/issuer/README.md

Example cURL command to create a PaymentReceiptCredential.

```sh
curl --request POST \
  --url http://localhost:3456/credentials/receipts \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:wallet' \
  --data '{
  "metadata": {
    "txHash": "0x123abc456def"
  },
  "payerDid": "did:web:0.0.0.0%3A3458:wallet",
  "paymentRequestToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "paymentOptionId": "option1"
}'
```

--------------------------------

### Creating DID URIs

Source: https://github.com/agentcommercekit/ack/blob/main/packages/did/README.md

Examples of creating different types of DID URIs (did:web, did:key, did:pkh).

```ts
import {
  createDidKeyUri,
  createDidPkhUri,
  createDidWebUri,
} from "@agentcommercekit/did"
import { generateKeypair } from "@agentcommercekit/keys"

// Create a did:web URI from a domain or URL
const webDid = createDidWebUri("https://www.example.com")
// did:web:example.com

// Create a did:key URI from a keypair
const keypair = await generateKeypair("secp256k1")
const keyDid = createDidKeyUri(keypair)
// did:key:zQ3...

// Create a did:pkh URI from an address and chain ID
const pkhDid = createDidPkhUri(
  "eip155:1",
  "0x1234567890123456789012345678901234567890",
)
// did:pkh:eip155:1:0x1234567890123456789012345678901234567890
```

--------------------------------

### A2A Methods Example

Source: https://github.com/agentcommercekit/ack/blob/main/packages/agentcommercekit/README.md

Example of importing a method for A2A identity exchange from the agentcommercekit/a2a module.

```typescript
import { createA2AHandshakeMessage } from "agentcommercekit/a2a"

// ...
```

--------------------------------

### Creating DID Documents

Source: https://github.com/agentcommercekit/ack/blob/main/packages/did/README.md

Examples of creating DID documents from keypairs, including generic and did:web specific documents.

```ts
import {
  createDidDocumentFromKeypair,
  createDidWebDocumentFromKeypair,
} from "@agentcommercekit/did"
import { generateKeypair } from "@agentcommercekit/keys"

const keypair = await generateKeypair("secp256k1")

// Create a DID document from a keypair
const did = createDidKeyUri(keypair)

const didDocument = createDidDocumentFromKeypair({
  did,
  keypair,
  encoding: "jwk", // Optional, defaults to "jwk"
  controller: "did:web:controller.example.com", // Optional
})

// Create a did:web and document with URI and document
const { did, didDocument } = createDidWebDocumentFromKeypair({
  keypair,
  baseUrl: "https://www.example.com",
  controller: ownerDid,
})
```

--------------------------------

### Create a JWT

Source: https://github.com/agentcommercekit/ack/blob/main/packages/jwt/README.md

Example of creating a JWT with a signer.

```ts
import { createJwt, createJwtSigner } from "@agentcommercekit/jwt"
import { generateKeypair } from "@agentcommercekit/keys"

// Generate a keypair
const keypair = await generateKeypair("secp256k1")

// Create a signer from the keypair
const signer = createJwtSigner(keypair)

// Create a JWT
const jwt = await createJwt(
  { sub: "did:web:subject.com", foo: "bar" },
  { issuer: "did:web:issuer.com", signer },
)
```

--------------------------------

### DID Document Endpoint

Source: https://github.com/agentcommercekit/ack/blob/main/docs/demos/example-identity.mdx

Sample cURL command to retrieve the issuer's DID Document.

```sh
curl --request GET \
  --url http://localhost:3456/.well-known/did.json
```

--------------------------------

### Verifying a Credential

Source: https://github.com/agentcommercekit/ack/blob/main/packages/vc/README.md

Example of parsing and verifying a JWT Verifiable Credential.

```ts
import {
  parsedJwtCredential,
  verifyParsedCredential,
} from "@agentcommercekit/vc"

// Parse JWT credential
const parsed = await parsedJwtCredential(jwt, resolver)

// Verify credential
await verifyParsedCredential(credential, {
  resolver,
  trustedIssuers: ["did:example:issuer"],
})
```

--------------------------------

### Payment Receipt Endpoints - Issue

Source: https://github.com/agentcommercekit/ack/blob/main/docs/demos/example-identity.mdx

Sample cURL command to issue a PaymentReceiptCredential.

```sh
curl --request POST \
  --url http://localhost:3456/credentials/receipts \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:wallet' \
  --data '{
  "metadata": { "txHash": "0x123abc456def" },
  "payerDid": "did:web:0.0.0.0%3A3458:wallet",
  "paymentRequestToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "paymentOptionId": "option1"
}'
```

--------------------------------

### DID Document Response Body

Source: https://github.com/agentcommercekit/ack/blob/main/examples/issuer/README.md

The response body for the GET /.well-known/did.json endpoint, returning the issuer's DID document.

```json
{
  "@context": [...],
  "id": "did:web:ృతి",
  "verificationMethod": [...],
  "authentication": [...],
  "assertionMethod": [...] 
}
```

--------------------------------

### Status Endpoint Response Body

Source: https://github.com/agentcommercekit/ack/blob/main/examples/issuer/README.md

The response body for the GET /status/:listId endpoint, retrieving a Bitstring Status List credential.

```json
{
  "ok": true,
  "data": "jwt-string"
}
```

--------------------------------

### Run the Development Server from the Current Directory

Source: https://github.com/agentcommercekit/ack/blob/main/docs/README.md

From the 'docs' directory, run this command to launch the documentation preview locally.

```sh
pnpm run docs
```

--------------------------------

### Usage Example

Source: https://github.com/agentcommercekit/ack/blob/main/packages/keys/README.md

Demonstrates generating keypairs, converting them to JWK format, and encoding public keys in various formats.

```ts
import {
  encodePublicKeyFromKeypair,
  generateKeypair,
  keypairToJwk,
} from "@agentcommercekit/keys"

// Generate and format keypairs
const keypair = await generateKeypair("secp256k1")
const jwkKeypair = keypairToJwk(keypair)

// Format public keys
const hexPublicKey = encodePublicKeyFromKeypair("hex", keypair)
const jwkPublicKey = encodePublicKeyFromKeypair("jwk", keypair)
const multibasePublicKey = encodePublicKeyFromKeypair("multibase", keypair)
const base58PublicKey = encodePublicKeyFromKeypair("base58", keypair)
```

--------------------------------

### Run from Repository Root

Source: https://github.com/agentcommercekit/ack/blob/main/docs/README.md

To preview documentation changes locally before committing, navigate to the repository root in your terminal and run this command.

```sh
pnpm dev:docs
```

--------------------------------

### Sample Output

Source: https://github.com/agentcommercekit/ack/blob/main/demos/skyfire-kya/README.md

Example output from running the Skyfire KYA integration demo.

```txt
Skyfire ACK-ID Integration Demo

1. Converting KYA JWT to ACK-ID compatible Verifiable Credential...
✓ Verifiable Credential created

2. Demonstrating bidirectional conversion...
✓ Successfully converted VC back to JWT:
   Original JWT matches reconstructed: true

3. Running ACK-ID style verification...
✓ Verification passed - agent is authorized

4. Simulating service interaction...
   Incoming request with KYA token...
   Serving agent: BuyerAgent
   Buyer name: Alice Johnson
   ✓ Request processed successfully

Demo complete
```

--------------------------------

### Running the demo

Source: https://github.com/agentcommercekit/ack/blob/main/demos/payments/README.md

Instructions on how to run the ACK-Pay payments demo from the root of the repository or from the current directory.

```sh
pnpm run demo:payments
```

```sh
pnpm run demo
```

--------------------------------

### Installation

Source: https://github.com/agentcommercekit/ack/blob/main/packages/caip/README.md

Install the @agentcommercekit/caip package using npm or pnpm.

```sh
npm i @agentcommercekit/caip
# or
pnpm add @agentcommercekit/caip
```

--------------------------------

### Demos

Source: https://github.com/agentcommercekit/ack/blob/main/AGENTS.md

Commands to run various protocol demonstrations.

```bash
pnpm demo:identity        # ACK-ID protocol demo
pnpm demo:identity-a2a    # ACK-ID with Google A2A protocol
pnpm demo:payments        # ACK-Pay protocol demo
pnpm demo:e2e             # End-to-end (ACK-ID + ACK-Pay)
pnpm demo:skyfire-kya     # Skyfire KYA token demo
```

--------------------------------

### Installation

Source: https://github.com/agentcommercekit/ack/blob/main/packages/ack-id/README.md

Install the ACK-ID package using npm or pnpm.

```sh
npm i @agentcommercekit/ack-id
# or
pnpm add @agentcommercekit/ack-id
```

--------------------------------

### Run all demos

Source: https://github.com/agentcommercekit/ack/blob/main/demos/README.md

Command to run all demos from the root of the project.

```sh
pnpm demo:identity
pnpm demo:payments
pnpm demo:e2e
```

--------------------------------

### Algorithm Mapping Example

Source: https://github.com/agentcommercekit/ack/blob/main/packages/jwt/README.md

Example of converting a cryptographic curve to its corresponding JWT algorithm using curveToJwtAlgorithm.

```ts
import { curveToJwtAlgorithm } from "@agentcommercekit/jwt"
import { generateKeypair } from "@agentcommercekit/keys"

const keypair = await generateKeypair("secp256k1")
const algorithm = curveToJwtAlgorithm(keypair.curve) // "ES256K"
```

--------------------------------

### Running the Demo from Repository Root

Source: https://github.com/agentcommercekit/ack/blob/main/docs/demos/demo-identity.mdx

Execute the following from the repository root:

```sh
pnpm run demo:identity
```

--------------------------------

### Running the demo command

Source: https://github.com/agentcommercekit/ack/blob/main/demos/skyfire-kya/README.md

Command to run the Skyfire KYA demo from the root of the repository.

```sh
pnpm run demo:skyfire-kya
```

--------------------------------

### Run Demo Command

Source: https://github.com/agentcommercekit/ack/blob/main/docs/demos/demo-payments.mdx

Command to run the payments demo from the repository root.

```sh
pnpm run demo:payments
```

--------------------------------

### Example ACK Receipt Verifiable Credential

Source: https://github.com/agentcommercekit/ack/blob/main/docs/ack-pay/receipt-verification.mdx

This JSON object represents an example of an ACK Receipt, structured as a W3C Verifiable Credential.

```json
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://agentcommercekit.org/contexts/payment/v1" // Example ACK context
  ],
  "id": "urn:uuid:5c358383-1d93-4956-8d0c-6e41e4d29901", // Unique receipt ID
  "type": ["VerifiableCredential", "ACKPaymentReceipt"],
  "issuer": "did:web:receipts.example.com", // DID of the trusted Receipt Service
  "issuanceDate": "2025-04-04T14:22:18Z",
  "credentialSubject": {
    // ID of the entity that made the payment (Client Agent DID)
    "id": "did:key:z6MkmCJAZansQ3d7Mi6moQoAFj6vpuPP9e4vWKsjWEY4Hd9t",
    "paymentRequestToken": "<signed-representation-of-the-payment-request-structure>",
    "paymentOptionId": "unique-payment-option-id-123", // The payment option that was used to make the payment
    "metadata": {
      // Additional metadata about the payment, depending on the payment option
      "amount": 1000, // Final settled amount (e.g., 10.00 USD)
      "currency": "USD", // Final settled currency
      "decimals": 2,
      // Identifier of the ultimate recipient (e.g., Server Agent DID or account)
      "recipient": "did:web:service.example.com",
      "id": "unique-request-id-123", // Links back to the Payment Request (if applicable)
      "serviceDescription": "Premium API access (100 credits)", // From original request (if applicable)
      "timestamp": "2025-04-04T14:22:15Z" // Timestamp of successful settlement
      // Optionally include settlement transaction hash/ID if relevant
      // "settlementRef": "stripe_charge_id_xyz"
    }
  },
  "proof": {
    // Standard VC proof (digital signature)
    "type": "Ed25519Signature2020",
    "created": "2025-04-04T14:22:18Z",
    "verificationMethod": "did:web:receipts.example.com#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3..." // Signature value
  }
}
```

--------------------------------

### Verify a JWT

Source: https://github.com/agentcommercekit/ack/blob/main/packages/jwt/README.md

Example of verifying a JWT.

```ts
import { getDidResolver } from "@agentcommercekit/did"
import { verifyJwt } from "@agentcommercekit/jwt"

const resolver = getDidResolver()

const parsed = await verifyJwt(payload, {
  resolver: didResolver,
})

console.log(parsed.payload)
```