Kwami

Kwami v3 is a Solana NFT collection and fully on-chain web3 app. Connect with Phantom, fund via MoonPay, mint a Kwami, publish it, and let others challenge it in a timed voice duel for a share of its account balance.

Mint · fund · publish · challenge · win (or grow the pot)

Table of contents

• Overview
• Features
• How it works
• Wallet & onboarding
• Getting started
• Scripts
• Project structure
• Documentation
• Contributing
• Security
• Releases
• License

Overview

Kwami combines a Solana NFT, a funded on-chain account, and a voice AI companion. Authors mint and publish Kwamis; challengers pay in SOL or USDC for a 3-minute voice session to discover the secret word or phrase.

Kwamis are immutable metadata but transferable assets — they can be bought and sold. The 3D model can be embedded in third-party apps. Minted owners unlock an AI program builder that generates Solana sub-programs for complex financial games before publish.

Features

• Solana NFT collection — mint, own, transfer, and trade Kwamis
• Phantom wallet — connect and sign on Solana
• MoonPay on-ramp — fiat → SOL/USDC without leaving the app
• Paid voice challenges — SOL or USDC tickets, 3-minute sessions
• Account economics — 80% reward on win; pot grows on miss
• Kwami death — dies after losing 99% of account value, or when balance falls under ~$1 USD
• Immutable + transferable — metadata locked; ownership can change on secondary markets
• Embeddable 3D model — integrate the Kwami avatar in any third-party app
• AI program builder — generate Solana sub-programs and smart-contract logic for custom financial games before publishing

How it works

Author                         Challenger
──────                         ──────────
Mint Kwami NFT
Fund account (SOL / USDC)
Set secret word/phrase
Customize on-chain logic
        │  Publish
        ▼
                  Pay ticket (SOL / USDC)
                  Speak to Kwami (≤ 3 min)
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
        Secret guessed              Time / miss
        → 80% balance               → ticket lost
          to challenger               pot grows

Wallet & onboarding

Getting started

Prerequisites

pnpm-lock.yaml is the lockfile of record. CI installs with --frozen-lockfile; an npm install here produces a lockfile CI will reject.

Install

git clone https://github.com/kwami-labs/kwami.git
cd kwami
nvm use
corepack enable
pnpm install    # also installs husky hooks

Build & verify

pnpm build
pnpm lint && pnpm typecheck && pnpm test:run

Consume the package

pnpm add kwami          # latest stable (main)
pnpm add kwami@rc       # release candidate (stg)
pnpm add kwami@dev      # prerelease (dev)

three is a peer dependency when embedding the 3D model:

pnpm add three

Scripts

# Build
pnpm build              # bundle + type declarations → dist/
pnpm dev                # rebuild on change
pnpm clean              # remove dist/, coverage/, and test output

# Quality
pnpm lint
pnpm lint:fix
pnpm format
pnpm format:check
pnpm typecheck
pnpm audit:ci

# Tests — see docs/testing.md
pnpm test               # unit
pnpm test:watch
pnpm test:coverage      # unit + coverage ratchet (CI)
pnpm test:integration
pnpm test:e2e           # built bundle in a real browser (WebGL)
pnpm test:all

# Releases — see docs/releases.md
pnpm release:dry-run    # print next version; change nothing

Project structure

kwami/
├── src/                  # Library & app source
│   ├── agent/            # Voice pipeline
│   ├── avatar/           # 3D renderers
│   ├── memory/           # Memory adapters
│   ├── soul/             # Personality
│   ├── skills/           # Native behaviors
│   ├── tools/            # Tool registry (MCP)
│   ├── types/            # TypeScript definitions
│   └── Kwami.ts          # Public entry surface
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── scripts/
│   ├── ci/               # Pipeline gates
│   └── release/          # Baseline tag, back-merge
├── docs/                 # Deep-dive guides
├── .github/              # Workflows, PR template, CODEOWNERS
├── CHANGELOG.md          # Generated by semantic-release
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE               # Apache-2.0
└── package.json

Documentation

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a PR.

Branch promotion (enforced in CI):

feature/* ──► dev ──► stg ──► main

• Branch off dev; open PRs against dev
• Use Conventional Commits — versions, tags, changelog, and npm publishes are derived from them
• Feature PRs are squash-merged; the PR title becomes the release subject
• Before push: pnpm lint && pnpm typecheck && pnpm test:unit && pnpm test:integration

Issue tracker: github.com/kwami-labs/kwami/issues

Security

Do not open public issues for vulnerabilities.

Report privately via GitHub Security Advisories or see SECURITY.md for supported versions, scope, and response expectations.

Releases

Releases are automated with semantic-release. Do not hand-edit CHANGELOG.md or the version field.

Details: docs/releases.md · History: CHANGELOG.md

License

Copyright © 2025 Alex Colls Outumuro

Licensed under the Apache License, Version 2.0. See the LICENSE file for the full text.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.