> ## 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.

# Quickstart

> The fastest path to understanding a Rako integration.

# Quickstart

Rako integrations revolve around a five-step attribution lifecycle:

```text theme={null}
search → recommend → checkout-link handoff → convert → settle
```

These are lifecycle stages, not MCP tool names. For MCP-compatible clients, use `search_offers -> get_checkout_requirements -> get_checkout_link`.

1. **Search** — an agent asks Rako for eligible offers matching user intent.
2. **Recommend** — the agent presents an offer and records the attribution event.
3. **Checkout** — the agent requests a hosted checkout URL or handoff for the recorded recommendation.
4. **Convert** — Rako reconciles later platform-side outcome evidence, such as a payment event, merchant report, or milestone, into the conversion ledger. The hosted payment-verification path is currently beta and should not be described as trustless until the full event authentication and AAP Code verification gate is deployed.
5. **Settle** — Rako validates the conversion, handles disputes or clawbacks, and calculates merchant commission, network fee, and builder payout.

## Minimal API sequence

```http theme={null}
GET /v1/offers?vertical=sim&data_gb_min=10&contract_months=0
```

```http theme={null}
POST /v1/recommend
Content-Type: application/json

{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "offerId": "01JQXK1001EXAMPLEOFFER001",
  "context": "User asked for a cheap no-contract SIM with at least 10GB"
}
```

```http theme={null}
POST /v1/checkout
Content-Type: application/json

{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "recommendationId": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ"
}
```

The checkout response returns a `checkoutUrl` when hosted checkout is available. That URL is a checkout handoff, not conversion proof. Rako attaches AAP context server-side so later platform-side outcome evidence can be joined back to the recommendation. In production, that join must be backed by authenticated outcome evidence and reconciliation checks before it is treated as verified.

## Fastest path: MCP

Add the Rako MCP server to an MCP-compatible client:

```json mcp-config.json theme={null}
{
  "mcpServers": {
    "aap": {
      "command": "bunx",
      "args": ["@rakohq/mcp"],
      "env": {
        "AAP_API_KEY": "your-api-key"
      }
    }
  }
}
```

Then let your agent call the canonical checkout-link flow:

1. `search_offers` to find eligible offers.
2. `get_checkout_requirements` to inspect what is needed before checkout-link creation.
3. `get_checkout_link` to request the hosted checkout handoff.

The MCP flow returns checkout-link metadata only; it does not process payment, prove conversion, confirm commission, or settle anything.

## Run locally first

<CardGroup cols={2}>
  <Card title="Runnable local examples" href="/examples/overview">
    Use the mock AAP server and SDK hello-world examples with fake data before wiring a non-mock API key.
  </Card>

  <Card title="MCP flow tutorial" href="/guides/mcp-agent-flow">
    Follow the canonical `search_offers -> get_checkout_requirements -> get_checkout_link` flow.
  </Card>
</CardGroup>

If the mock server's default `PORT=3456` is already in use, start it on another port and set the clients to the same URL:

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

## SDK paths

<CardGroup cols={2}>
  <Card title="JavaScript SDK" href="/sdks/javascript">
    Use `@rakohq/sdk` from Node.js, Deno, or Bun.
  </Card>

  <Card title="Python SDK" href="/sdks/python">
    Use `agent-attribution-protocol` from Python agents and services.
  </Card>
</CardGroup>