5-minute guide

First connector call, fast

One SDK. One spec file. Your AI agent connected to the MENA (and Gmail) before your coffee cools.

Gmail — global connector STC Pay — MENA connector

1 Install
2 Load spec
3 Authorize
4 Execute
5 Live!

Install the SDK

The Wassl SDK bundles the connector runtime, vault, and spec loader.

npm

npm install @wasl/sdk @wasl/runtime

pip / uv

pip install wasl-sdk
# or with uv:
uv add wasl-sdk

shell

# curl users: skip to Step 3 — the control plane's /api/connectors
# endpoint needs no SDK. Or install the SDK for full auth + retry support.
curl https://api.wassel.cloud/api/connectors | jq '.[].id'

Prerequisites: Node.js ≥ 20 (TS) · Python ≥ 3.11 (Python)

Choose a connector

Pick one to try. Each connector is a YAML spec that describes auth, actions, and rate limits.

TypeScript

import { Connectors } from "@wasl/sdk";

const client = await Connectors.fromDir("./connectors"); // loads gmail.yaml
console.log(client.list().map(c => c.id));
// ["gmail"]

Python

from wasl import Connectors

client = Connectors.from_dir("./connectors")   # loads gmail.yaml
print([c.id for c in client.list()])
# ["gmail"]

curl

curl https://api.wassel.cloud/api/connectors \
  | jq '.[] | select(.id=="gmail")'

🌍

Gmail Global · OAuth2 · Communication

TypeScript

import { Connectors } from "@wasl/sdk";

const client = await Connectors.fromDir("./connectors"); // loads stc-pay.yaml
console.log(client.list().map(c => c.id));
// ["stc-pay"]

Python

from wasl import Connectors

client = Connectors.from_dir("./connectors")   # loads stc-pay.yaml
print([c.id for c in client.list()])
# ["stc-pay"]

curl

curl https://api.wassel.cloud/api/connectors \
  | jq '.[] | select(.id=="stc-pay")'

🇸🇦

STC Pay KSA · OAuth2 Client Credentials · Payments

Spec files are bundled with the SDK. Place any .yaml spec in a ./connectors/ directory and the SDK discovers them automatically. GitHub repo coming soon.

Authorize

Generate an OAuth2 URL. Your user authenticates once; Wassl handles token storage and refresh.

TypeScript

const { url, state } = client.authorize("gmail", {
  clientId: process.env.GMAIL_CLIENT_ID!,
  redirectUri: "https://myapp.com/auth/callback",
  scopes: ["gmail.send", "gmail.readonly"],
});

// Redirect your user to `url`, then exchange the code on callback.
console.log("Auth URL:", url);

Python

result = client.authorize(
    "gmail",
    client_id="your-google-client-id",
    redirect_uri="https://myapp.com/auth/callback",
    scopes=["gmail.send", "gmail.readonly"],
)
print("Auth URL:", result.url[:80] + "…")
print("State:", result.state)

shell

# Gmail uses Authorization Code flow. Generate the URL manually:
open "https://accounts.google.com/o/oauth2/auth?\
  client_id=YOUR_CLIENT_ID\
  &redirect_uri=https://myapp.com/callback\
  &response_type=code\
  &scope=https://mail.google.com/"

TypeScript

// STC Pay uses Client Credentials — no user redirect needed.
const { url } = client.authorize("stc-pay", {
  clientId: process.env.STC_CLIENT_ID!,
  clientSecret: process.env.STC_CLIENT_SECRET!,
});
// url points to https://sandbox.stcpay.com.sa/b2b/oauth2/token
// The SDK exchanges credentials and caches the access token automatically.

Python

# STC Pay uses Client Credentials — no user redirect needed.
result = client.authorize(
    "stc-pay",
    client_id="your-stc-client-id",
    client_secret="your-stc-client-secret",
)
# The SDK fetches and caches the access token automatically.

curl

# STC Pay sandbox — Client Credentials
curl -X POST https://sandbox.stcpay.com.sa/b2b/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials\
&client_id=$STC_CLIENT_ID\
&client_secret=$STC_CLIENT_SECRET"

Sandbox credentials: Register for STC Pay sandbox · Google Cloud Console for Gmail. Both provide test environments with no real money or email sent.

Execute your first action

One call to run any action on any connector. Wassl handles retries, rate limits, and token refresh.

TypeScript

const result = await client.execute(
  "gmail",
  "get_profile",
  {},
  { token: process.env.GMAIL_ACCESS_TOKEN! },
);

// { status: 200, body: { emailAddress: "alice@example.com", ... }, attempts: 1 }
console.log("Inbox belongs to:", result.body.emailAddress);

Python

import asyncio
from wasl import Connectors

async def run():
    result = await client.execute(
        "gmail",
        "get_profile",
        ,
        credential={"token": "ya29.your-access-token"},
    )
    print("Inbox:", result.body["emailAddress"])

asyncio.run(run())

curl

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/profile" \
  -H "Authorization: Bearer $GMAIL_ACCESS_TOKEN" | jq .emailAddress

TypeScript

const result = await client.execute(
  "stc-pay",
  "send_payment",
  {
    mobile: "+966501234567",
    amount: 1.00,          // SAR — sandbox minimum
    currency: "SAR",
    referenceId: "test-001",
  },
  { token: process.env.STC_ACCESS_TOKEN! },
);

// { status: 200, body: { transactionRef: "TX-...", otpRef: "..." }, attempts: 1 }
console.log("Transaction:", result.body.transactionRef);

Python

import asyncio

async def run():
    result = await client.execute(
        "stc-pay",
        "send_payment",
        {
            "mobile": "+966501234567",
            "amount": 1.00,
            "currency": "SAR",
            "referenceId": "test-001",
        },
        credential={"token": os.environ["STC_ACCESS_TOKEN"]},
    )
    print("Transaction:", result.body["transactionRef"])

asyncio.run(run())

curl

# STC Pay sandbox — initiate payment
curl -X POST https://sandbox.stcpay.com.sa/b2b/payment/doDirectPayment \
  -H "Authorization: Bearer $STC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "MobileNo": "+966501234567",
    "Amount": 1.00,
    "Currency": "SAR",
    "BranchID": "001",
    "TellerID": "001",
    "DirectPaymentID": "test-001"
  }'

✓

You're live

Your first connector call just went through. Wassl logged the latency, success rate, and retry count. Head to the status page to see it land.

View live status → Browse all connectors

What's next

Add more connectors — drop any .yaml spec into your ./connectors/ dir and call client.list() to see it.
Claude / MCP — run the Wassl MCP server and expose every connector as a tool in Claude Code or any MCP-compatible agent.
MENA rails — Salla, Moyasar, Lean, HungerStation, Careem, and 10+ more. All available today.
Contribute a connector — YAML spec + a PR. GitHub repo and contributing guide coming soon.