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

# Run the sample app locally

> Copy-paste setup. Five minutes once you have Node and Lace.

Every command block below tells you which directory to run it from. Follow top to bottom, nothing else needed.

## Prerequisites

* Node.js 20+ and npm 10+
* Git
* [Lace wallet](https://www.lace.io) extension, set to Preprod
* Free [Blockfrost](https://blockfrost.io) project id (Preprod network)
* (Optional) [OpenAI API key](https://platform.openai.com/api-keys) if you want the AI agent panel

## 1. Clone the repo and install

```bash theme={null}
# any dir
git clone https://github.com/SkepX/charli3-js.git
cd charli3-js/demo-nextjs
npm install
```

The app imports `charli3-js` from npm, so there is no SDK build step.

## 2. Generate the demo wallet and contract address

```bash theme={null}
# in charli3-js/demo-nextjs/
npm run setup
```

This prints two addresses. Copy the second one (`wallet address : addr_test1...`) — you will paste it into the faucet next. The seed is saved to `demo-nextjs/.wallet.seed` (gitignored).

<Note>
  The output lines that start with `script address :` and `wallet address :` are **printed output**, not commands to run.
</Note>

## 3. Fund the demo wallet

Go to the [Cardano preprod faucet](https://docs.cardano.org/cardano-testnets/tools/faucet), paste the `wallet address` from step 2, and send 10 000 tADA. This wallet pays for Round 2 refreshes on the server. Your own Lace wallet is separate.

## 4. Set the env

Create `demo-nextjs/.env.local` with your Blockfrost id (and optionally your OpenAI key):

```bash theme={null}
NEXT_PUBLIC_BLOCKFROST_PROJECT_ID=preprod...
OPENAI_API_KEY=sk-...
```

<Tip>
  The Blockfrost id has `NEXT_PUBLIC_` in front because Lucid runs in the browser when you sign with Lace. Project ids are scoped and rate-limited so exposing them is fine.
</Tip>

## 5. Run it

```bash theme={null}
# in charli3-js/demo-nextjs/
npm run dev
```

Open [http://localhost:3000](http://localhost:3000). You should see a live ADA/USD price rendered from chain within a second.

## What to click first

1. Scroll to **Run the loop**, click **Connect Lace**, then **Deposit 3 tADA**.
2. Click **Refresh oracle price**. The server pays the fee with the demo seed from step 2.
3. Click **Claim locked tADA**. The Aiken validator releases the deposit because the price cleared the threshold.
4. Scroll to **AI agent**, drop the sample invoice, and sign the payment with Lace.

## Troubleshooting

<AccordionGroup>
  <Accordion title="`next: command not found` when I run npm run dev">
    You're in `demo-nextjs/` but never ran `npm install` there. Run it, then `npm run dev` again.
  </Accordion>

  <Accordion title="`Missing script: setup` or `Missing script: dev`">
    These scripts live in `demo-nextjs/package.json`, not the repo root. `cd demo-nextjs` first.
  </Accordion>

  <Accordion title="`zsh: command not found: script` or `: wallet`">
    You pasted the example output of step 2 as commands. `script address :` and `wallet address :` are **printed**, not run.
  </Accordion>

  <Accordion title="Hero price shows --">
    Kupo endpoint hiccup. Retry the page.
  </Accordion>

  <Accordion title="`Lace is on network 1, switch to preprod`">
    Open Lace, Settings, Network, switch to Preprod Testnet, reconnect.
  </Accordion>

  <Accordion title="Refresh button stuck on `Building tx`">
    The demo wallet ran out of tADA, or Blockfrost is throttling. Refund at the faucet and try again.
  </Accordion>

  <Accordion title="`script artifacts unavailable` or `Cannot convert undefined to a BigInt`">
    `demo-nextjs/artifacts.json` is missing. Re-run `npm run setup` from `demo-nextjs/`.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Walkthrough" icon="list-check" href="/example-app/walkthrough">
    Guided tour of every panel in the UI.
  </Card>

  <Card title="How the SDK works" icon="gears" href="/concepts/how-it-works">
    Round 1 / Round 2, IQR consensus, datum layout.
  </Card>
</CardGroup>