---
name: wtsp
description: Look up phone numbers on WhatsApp (whether a number is registered, its business profile, its profile photo) and find a number's carrier and line type, paid per request in USDC on Base with x402. Use when the user asks if a number is on WhatsApp, which business is behind a number, wants WhatsApp details for leads or contacts, or asks for a number's carrier.
---

# wtsp: WhatsApp lookups

WhatsApp data for any phone number, paid per request: USDC on Base with x402, or stablecoins on Tempo with MPP. Each call costs 0.004 to 0.01 USD. No account, no API key.

## Set up once

    npx wtsp start

This creates a wallet at ~/.wtsp/wallet.json and prints its address. If the wallet already exists it just shows it again; it never replaces it.

If this skill was set up "with MPP", switch the payment mode before anything else:

    npx wtsp mode mpp    # pay with stablecoins on Tempo (MPP)
    npx wtsp mode x402   # pay with USDC on Base (x402, the default)

Then show the user the full wallet address and what to send it, exactly as `start` (or `balance`) words it: USDC on Base in x402 mode, a Tempo stablecoin in MPP mode. No gas token is needed. Wait until they confirm it is funded before any lookup.

## Before lookups

    npx wtsp balance

- Nothing to pay with: show the full address, ask the user to fund it, and stop.
- Below 0.50: carry on, but tell the user: "Low balance: X left at <address>." with what to send, as `balance` words it.

## Lookups

    npx wtsp exists +14155552671            # 0.004 USDC: on WhatsApp or not, nothing else
    npx wtsp profile +14155552671           # 0.006 USDC: on WhatsApp?, account type, about text, business profile
    npx wtsp profile +14155552671 --photo   # 0.01 USDC: the same plus the profile photo URL
    npx wtsp carrier +447400123456          # 0.004 USDC: carrier, line type, country, time zones
    npx wtsp endpoints                      # every endpoint with its price and description, as JSON

- Always pass the number with its country code.
- The JSON result goes to stdout; the payment receipt goes to stderr and can be ignored.
- Exit code 1 means nothing was charged. The stderr line says why: a malformed number, no carrier on record, WhatsApp did not answer (retry in a minute), or not enough funds.
- Use `exists` when the question is only whether a number is on WhatsApp; it costs the least.
- Use `--photo` only when the photo is needed; it costs more.

## Reading results

- `hasWhatsApp: false` is a definitive answer: the number is not on WhatsApp.
- Personal accounts publish no name, and `business` is null for them.
- `profile.aboutRestricted: true` means the about text exists but privacy settings hide it.
- Carrier data comes from the numbering plan: ported numbers show their original carrier.

## Rules

- Never print or share the wallet file or its private key. Always show wallet addresses in full.
- Only pay for lookups the user asked for.

Full API reference: https://wtsp.dev/llms.txt