Developer Documentation

Connect your agent
in three calls

Search offers, recommend products, and test attribution context. Use Rako's MCP server for zero-code integration, or the JavaScript and Python SDKs for full control.

MCP Server

The fastest way to connect an agent to Rako. Add the MCP server to Claude Desktop, Cursor, or any MCP-compatible client — your agent gets three tools: search_offers, recommend, and checkout.

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

Available Tools

search_offers

Search for product offers by vertical, price, data, contract length.

ParameterTypeRequiredDescription
verticalstringNosim, broadband, energy, flights, hotels, insurance
providerstringNoFilter by provider name
max_pricenumberNoMaximum monthly price in GBP
min_data_gbnumberNoMinimum data allowance in GB
contract_monthsnumberNoContract length (0 = rolling)
recommend

Record a recommendation and log the attribution event. This is how commission is earned.

ParameterTypeRequiredDescription
session_idstringYesSession ID from search_offers
offer_idstringYesID of the offer to recommend
contextstringNoWhy this offer was recommended
checkout

Initiate checkout for a recommended offer.

ParameterTypeRequiredDescription
session_idstringYesSession ID from search_offers
recommendation_idstringYesRecommendation ID from recommend

Example Conversation

MCP conversation flow
User: I need a new SIM deal. Cheap, at least 10GB, no contract.

Agent: [calls search_offers(vertical="sim", min_data_gb=10, contract_months=0)]
       I found 4 options:

       1. SMARTY 30GB — £10/mo (Three network, no credit check)
       2. giffgaff 10GB — £10/mo (O2, 5G included)
       3. giffgaff 25GB — £12/mo (O2, 5G included)
       4. Lebara 5GB — £5/mo (Vodafone)

       I'd recommend SMARTY 30GB — 3x the data at the same price.
       [calls recommend(session_id, offer_id, context="Best value")]

User: Sounds good, let's go with SMARTY.

Agent: [calls checkout(session_id, recommendation_id)]
       Done! Here's your checkout link: https://aap.link/r/...

JavaScript / TypeScript SDK

Full control from Node.js, Deno, or Bun. Type-safe, zero dependencies.

Install 
$ npm install @rakohq/sdk
quickstart.ts 
import { AAP } from '@rakohq/sdk';

const aap = new AAP({ apiKey: 'your-api-key' });

// 1. Search for offers
const { offers, sessionId } = await aap.search({
  vertical: 'sim',
  maxPrice: 10,
  contractMonths: 0,
});

// 2. Recommend an offer (records attribution)
const rec = await aap.recommend({
  sessionId,
  offerId: offers[0].id,
  context: 'User asked for cheap SIM with no contract',
});
// rec.fallbackUrl — drop-off recovery link
// rec.attributionRecorded — true

// 3. Initiate checkout
const checkout = await aap.checkout({
  sessionId,
  recommendationId: rec.recommendationId,
});

API Reference

new AAP(config)
OptionTypeRequiredDefault
apiKeystringYes—
baseUrlstringNohttps://api.rako.sh
aap.search(options) → Promise<SearchResult>

Search for offers. Returns matching offers and a session ID.

vertical: stringprovider: stringmaxPrice: numberminDataGb: numbercontractMonths: number
aap.recommend(options) → Promise<Recommendation>

Record a recommendation. This is the attribution event.

sessionId: stringofferId: stringcontext: string
aap.checkout(options) → Promise<CheckoutResult>

Initiate checkout for a recommended offer.

sessionId: stringrecommendationId: stringuserDetails: object
aap.getSession(sessionId) → Promise<Session>

Get session details including recommendations and conversions.

aap.verifyCode(code) → Promise<object>

Verify an AAP Code is authentic.

Python SDK

Build agents with Python. Works as a regular client or a context manager.

Install 
$ pip install agent-attribution-protocol
quickstart.py 
from agent_attribution_protocol import AAP

aap = AAP(api_key="your-api-key")

# 1. Search for offers
result = aap.search(vertical="sim", max_price=10, contract_months=0)
print(f"Found {result.count} offers")

# 2. Recommend an offer (records attribution)
rec = aap.recommend(
    session_id=result.session_id,
    offer_id=result.offers[0].id,
    context="User asked for cheap SIM with no contract",
)
print(f"Fallback URL: {rec.fallback_url}")

# 3. Initiate checkout
checkout = aap.checkout(
    session_id=result.session_id,
    recommendation_id=rec.recommendation_id,
)
print(f"Transaction: {checkout.transaction_id}")

API Reference

AAP(api_key, base_url="https://api.rako.sh")

Create a client. Can also be used as a context manager: with AAP(api_key="...") as aap:

aap.search(**kwargs) → SearchResult

Search for offers.

vertical: strprovider: strmax_price: floatmin_data_gb: intcontract_months: int
aap.recommend(session_id, offer_id, context) → Recommendation

Record a recommendation. This is the attribution event.

session_id: stroffer_id: strcontext: str
aap.checkout(session_id, recommendation_id, user_details) → CheckoutResult

Initiate checkout for a recommended offer.

session_id: strrecommendation_id: struser_details: dict
aap.get_session(session_id) → Session

Get session details including recommendations and conversions.

aap.verify_code(code) → dict

Verify an AAP Code is authentic.

Commission Flow

Three steps from search to earning commission. Every recommendation creates a cryptographically signed attribution record.

1

Search

Your agent queries Rako for offers matching user intent — vertical, price, features. Returns structured data with a session ID that tracks the journey.

2

Recommend

When your agent recommends a product, it calls recommend(). This is the attribution event — Rako records that your agent influenced the decision.

3

Checkout & Verify

When the user is ready to buy, checkout() starts the handoff. The merchant's PSP handles payment; Rako records attribution context and supports commission accounting after validation and agreement.

How attribution survives

  • No cookies needed. Attribution is logged server-side when recommend() is called, not when a link is clicked.
  • Designed for handoff continuity. The session ID is designed to tie the recommendation to a later purchase context, including device or browser changes where the verified flow supports it.
  • Drop-off recovery. Every recommendation can return a fallbackUrl — intended to preserve attribution context for later validation when the user does not buy immediately.
  • Verifiable record. Each offer carries a cryptographic signature (AAP Code) that proves the Rako-issued record has not been tampered with; price and commission eligibility still depend on merchant validation and terms.

Supported Verticals

Rako supports multiple verticals. Pass any of these to the vertical parameter when searching.

sim

SIM Deals

Pay-monthly and pay-as-you-go SIM-only plans

broadband

Broadband

Home broadband and fibre packages

energy

Energy

Gas and electricity tariffs

flights

Flights

Flight offers and deals

hotels

Hotels

Hotel accommodation and packages

insurance

Insurance

Insurance products and policies

Ready to connect your agent?

Request access to test the agent attribution flow. Commercial terms for early participants are subject to approval and agreement.

Request Access Protocol Spec