Skip to main content

​
Quickstart

Rako integrations revolve around a five-step attribution lifecycle: 
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

GET /v1/offers?vertical=sim&data_gb_min=10&contract_months=0

POST /v1/recommend
Content-Type: application/json

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

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:
mcp-config.json
{
  "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

Runnable local examples

Use the mock AAP server and SDK hello-world examples with fake data before wiring a non-mock API key.

MCP flow tutorial

Follow the canonical search_offers -> get_checkout_requirements -> get_checkout_link flow.
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: 
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

JavaScript SDK

Use @rakohq/sdk from Node.js, Deno, or Bun.

Python SDK

Use agent-attribution-protocol from Python agents and services.