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

# Runnable Examples

> Start the local mock AAP server and run the JavaScript, Python, and MCP-style examples with fake data.

# Runnable Examples

Use these examples when you want a local hello-world path before connecting to a non-mock Rako API key. They use placeholder credentials, deterministic mock offers, and a reserved `.invalid` checkout URL.

<Info>
  These examples do not process payment, collect payment details, promise conversion or payout, or mutate production/live data.
</Info>

## Fastest local path

1. Start the mock AAP server.
2. Run the JavaScript or Python SDK example against it.
3. Read the MCP transcript for the canonical agent-tool sequence.

```sh theme={null}
# Terminal 1
cd examples/mock-aap-server
npm install
AAP_API_KEY=aap_demo_key npm run start
```

```sh theme={null}
# Terminal 2: JavaScript/TypeScript
cd examples/js-sdk-basic
npm install
AAP_API_KEY=aap_demo_key AAP_API_URL=http://localhost:3456 npm run start
```

```sh theme={null}
# Terminal 2: Python
cd examples/python-sdk-basic
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
AAP_API_KEY=aap_demo_key AAP_API_URL=http://localhost:3456 python main.py
```

The `pip` upgrade is intentional for fresh local virtualenvs; editable `pyproject.toml` installs need modern `pip` support. `uv venv .venv && source .venv/bin/activate && uv pip install -e .` is the equivalent `uv` path.

Expected SDK output includes a mock offer, a mock recommendation ID, and:

```text theme={null}
Checkout URL: https://checkout.example.invalid/mock
```

## If port 3456 is already in use

If the mock server exits with `EADDRINUSE`, pick another local port and point the clients at the same URL:

```sh theme={null}
# Terminal 1
cd examples/mock-aap-server
PORT=45680 AAP_API_KEY=aap_demo_key npm run start
```

```sh theme={null}
# Terminal 2
AAP_API_KEY=aap_demo_key AAP_API_URL=http://localhost:45680 npm run start
```

Use the same `AAP_API_URL` value for the JavaScript and Python examples.

## MCP tool sequence

For MCP-compatible clients, the canonical checkout-link flow is:

```text theme={null}
search_offers -> get_checkout_requirements -> get_checkout_link
```

The mock transcript lives in the examples directory and is designed to be read before wiring a client to a non-mock API endpoint.

<Card title="MCP agent flow tutorial" href="/guides/mcp-agent-flow">
  Read the step-by-step version of the mock transcript and checkout-link handoff boundary.
</Card>

## Example directories

* `examples/README.md` — full local walkthrough and validation checklist.
* `examples/mock-aap-server` — tiny local server with fake offers and checkout links.
* [`examples/js-sdk-basic`](https://github.com/rakohq/developer-docs/tree/main/examples/js-sdk-basic) — JavaScript/TypeScript SDK hello world.
* [`examples/python-sdk-basic`](https://github.com/rakohq/developer-docs/tree/main/examples/python-sdk-basic) — Python SDK hello world.
* [`examples/mcp-agent-flow`](https://github.com/rakohq/developer-docs/tree/main/examples/mcp-agent-flow) — canonical MCP-style transcript.
* [`examples/mock-conversion`](https://github.com/rakohq/developer-docs/tree/main/examples/mock-conversion) — fake conversion artifact for local learning only.

<Card title="Mock conversion artifact" href="/guides/mock-conversion">
  Understand how the fake conversion payload relates to checkout-link creation.
</Card>