# Citrus Mobile

> Pay-as-you-go eSIM data in 220 destinations. Citrus Mobile also offers a
> Reseller API so developers can provision, fund, and manage eSIMs programmatically.

## Developer Documentation

- [Full docs, one file](https://citrusmobile.com/llms-full.txt): Complete API reference inlined — the fastest way for an agent to read everything.
- [API Reference (Markdown)](https://citrusmobile.com/developer/docs/markdown): Full, server-rendered Citrus Mobile Reseller API reference — every endpoint, parameter, and response. Also served at https://citrusmobile.com/developer/docs.md.
- [API Reference (interactive)](https://citrusmobile.com/developer/docs): Try any endpoint live from the browser.
- [OpenAPI Spec](https://citrusmobile.com/openapi-reseller.yaml): Machine-readable OpenAPI 3.1 source (YAML).
- [Developer Portal](https://citrusmobile.com/developer): Create an account and manage API keys.

## Agent Discovery

- [API Catalog](https://citrusmobile.com/.well-known/api-catalog): RFC 9727 linkset — spec, docs, and status links for every API.
- [Capability Manifest](https://citrusmobile.com/.well-known/ai-catalog.json): ARD manifest of every agent-facing capability.
- [MCP Server Card](https://citrusmobile.com/.well-known/mcp/server-card.json): Transport, capabilities, and tool list for the MCP server.
- [Agent Skills](https://citrusmobile.com/.well-known/agent-skills/index.json): Installable SKILL.md guides for provisioning eSIMs, pricing trips, and connecting over MCP.
- [Authentication](https://citrusmobile.com/auth.md): How to get and use a reseller API key. There is no OAuth flow.
- [Public agent tools](https://citrusmobile.com/api/agent-tools): GET for JSON Schema descriptors, POST `{"tool","input"}` to run one without MCP.
- Markdown: send `Accept: text/markdown` to any page on this site to get its Markdown rendering.

## MCP Server

Connect an AI agent directly to the Citrus Mobile API (streamable HTTP):

- Endpoint: `https://citrusmobile.com/api/mcp`
- Public tools, no auth: `get_rates`, `check_coverage`, `estimate_cost`, `search_docs`
- Account tools with a reseller API key header (`Authorization: Bearer rsk_...`): `get_account`, `list_esims`, `get_esim`, `provision_esim`, `fund_esim`
- Claude Code: `claude mcp add --transport http citrus https://citrusmobile.com/api/mcp` (add `--header "Authorization: Bearer rsk_..."` for account tools)

## Guides & Recipes

Practical walkthroughs with working code, at [https://citrusmobile.com/developer/guides](https://citrusmobile.com/developer/guides):

- [Pay-As-You-Go eSIM](https://citrusmobile.com/developer/guides#payg): Customer pays upfront, you fund their SIM.
- [Unlimited with Fair-Use Throttling](https://citrusmobile.com/developer/guides#unlimited): Flat-rate plan with a daily cap.
- [Country-Specific eSIMs](https://citrusmobile.com/developer/guides#country-specific): Destination-targeted storefront.
- [Travel eSIM Bundles](https://citrusmobile.com/developer/guides#travel-bundles): Batch-provision for tour groups.
- [Always-On Team Data](https://citrusmobile.com/developer/guides#shared-balance): One shared balance that refills itself.
- [White-Label Storefront](https://citrusmobile.com/developer/guides#white-label): Fully branded, Citrus invisible.
- [IoT / M2M Connectivity](https://citrusmobile.com/developer/guides#iot): Fleet-manage trackers and devices.

## Reseller API Endpoints

Base URL: `https://citrusmobile.com/api/v2/reseller` (Bearer API key, `rsk_` prefix)

- `POST /esim/provision` — Provision a new eSIM
- `GET /esim/list` — List your eSIMs
- `GET /esim/{iccid}` — Get eSIM details
- `POST /esim/{iccid}/enable` — Enable data on an eSIM
- `POST /esim/{iccid}/disable` — Disable data on an eSIM
- `POST /esim/{iccid}/terminate` — Terminate an eSIM
- `POST /esim/{iccid}/throttle` — Throttle SIM speed
- `POST /esim/{iccid}/defund` — Return an eSIM's unused balance
- `POST /esim/{iccid}/fund` — Fund an eSIM wallet
- `GET /groups` — List groups (New)
- `POST /groups` — Create a group (New)
- `GET /groups/{id}` — Get a group (New)
- `PATCH /groups/{id}` — Update a group (New)
- `POST /groups/{id}/fund` — Move funds into a group (New)
- `POST /groups/{id}/defund` — Return a group balance to your account (New)
- `GET /groups/{id}/esims` — List eSIMs in a group (New)
- `POST /groups/{id}/esims` — Add an eSIM to a group (New)
- `DELETE /groups/{id}/esims/{iccid}` — Remove an eSIM from a group (New)
- `GET /wallet/balance` — Get reseller account balance
- `GET /rates` — Get per-country data rates
- `GET /account` — Get account details
- `GET /webhooks` — List webhook endpoints
- `POST /webhooks` — Register a new webhook endpoint
- `GET /webhooks/{id}` — Get webhook detail
- `PUT /webhooks/{id}` — Update a webhook
- `DELETE /webhooks/{id}` — Delete a webhook
- `POST /webhooks/{id}/test` — Send a test event

## Product

- [Home](https://citrusmobile.com/): Product overview and supported countries.
- [Rates](https://citrusmobile.com/rates): Per-country data pricing.
- [Pricing](https://citrusmobile.com/pricing): How pricing works.
- [How It Works](https://citrusmobile.com/how-it-works): eSIM activation, billing, and running several eSIMs on one balance.
- [APN Settings](https://citrusmobile.com/apn-settings): APN values and setup steps for an eSIM that shows no data.
- [Compatible Devices](https://citrusmobile.com/esim-compatible-devices): Supported phones and tablets.
- [Support](https://citrusmobile.com/support): Help and contact.

## Product Facts

Details that are often gotten wrong when summarizing Citrus Mobile:

- Billing granularity: data is billed on actual usage down to the kilobyte. Nothing is rounded up to the next MB and there is no minimum charge per session. Usage is reconciled with the network every 10 minutes; that is the balance refresh cadence, not a billing block. Using 100 KB in each of six 10-minute windows costs 600 KB, not 6 MB.
- Multiple eSIMs are available to ordinary consumer accounts, not just resellers. Any customer can issue additional eSIMs from their account page for a one-time $2.45 USD issuance fee each; all eSIMs on an account draw on the same balance. Each eSIM installs on one device only.
- The first eSIM is free. The minimum top-up is $4 and balances never expire.
- APN values (any one works worldwide, no username or password): globaldata, internet, ispplus, orange, orange.fr. Full instructions at https://citrusmobile.com/apn-settings.

## Optional

- [Sitemap](https://citrusmobile.com/sitemap.xml): Full list of indexable pages, including per-country eSIM pages.