Cypher eSIM

Find a country, region or "world" destination by name or ISO code. Returns destination codes for list_plans (country: ISO2 like "JP"; region: like "R-EUROPE"; world: "WORLD"), starting prices in USD, and how many data and phone-number plans exist. An empty query lists all destinations.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 60,
      "description": "Country or region name, or ISO2 code, e.g. \"Japan\", \"JP\", \"Europe\""
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 300,
      "description": "Max results, default 20"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List purchasable plans for a destination, cheapest first. type "data" = data-only eSIM: validity starts on first connection at the destination. type "number" = eSIM with a phone number, calls and SMS: validity starts at installation, so install it just before use; Europe plans give a French +33 number; the UK number plan must be installed only after arrival in the UK. For a country without its own plans, regional and world plans that cover it are returned. Prices are final USD prices; the crypto amount is set at create_order.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "minLength": 2,
      "maxLength": 40,
      "description": "Destination code from search_destinations, or a country ISO2 code"
    },
    "type": {
      "type": "string",
      "enum": [
        "data",
        "number"
      ],
      "description": "\"data\" (default) or \"number\" (plan with a phone number)"
    },
    "include_regional": {
      "type": "boolean",
      "description": "For a country: also return regional/world plans covering it"
    }
  },
  "required": [
    "destination"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full details of one plan: all covered countries, data, days, phone number (if any), install rules, when validity starts, and notes. Read the notes to the person before create_order.

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 80,
      "description": "plan_id from list_plans"
    }
  },
  "required": [
    "plan_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Coins and networks accepted for payment. Pass coin and network to create_order. Sending on a different network loses the funds.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a crypto invoice for one new eSIM. Before calling, confirm the plan with the person and tell them when validity starts and the plan notes (number plans: validity starts at installation; Europe number is French +33; UK number plan: install only after arrival). Returns order_id, order_token, the exact amount and the address. The person must send exactly that amount on that network before expires_at. Then poll get_order. Unpaid invoices per client are limited; cancel unused ones with cancel_order.

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 80,
      "description": "plan_id from list_plans"
    },
    "coin": {
      "type": "string",
      "minLength": 2,
      "maxLength": 10,
      "description": "Coin code from list_payment_coins, e.g. \"USDT\", \"BTC\", \"XMR\""
    },
    "network": {
      "type": "string",
      "minLength": 2,
      "maxLength": 40,
      "description": "Network from list_payment_coins, e.g. \"tron\", \"solana\". Required for USDT (several networks)."
    },
    "ref": {
      "type": "string",
      "maxLength": 32,
      "description": "Optional partner/referral code"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Resellers with an API key only: number of identical eSIMs on one invoice (1-50). Omit otherwise."
    },
    "client_ref": {
      "type": "string",
      "maxLength": 64,
      "description": "Resellers only: your own order reference, returned as is."
    }
  },
  "required": [
    "plan_id",
    "coin"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Order status: pending (waiting for payment), paid (issuing), delivered, expired, failed. When delivered, returns for each eSIM: QR code (also as an image), LPA activation code, ICCID, and one-tap iOS/Android install links. Call at most once every 5 seconds.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "minLength": 10,
      "maxLength": 40,
      "description": "order_id returned by create_order"
    },
    "order_token": {
      "type": "string",
      "minLength": 20,
      "maxLength": 64,
      "description": "order_token returned by create_order"
    }
  },
  "required": [
    "order_id",
    "order_token"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancel an unpaid order the person decided not to pay. Do not cancel after the payment was sent.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "minLength": 10,
      "maxLength": 40,
      "description": "order_id returned by create_order"
    },
    "order_token": {
      "type": "string",
      "minLength": 20,
      "maxLength": 64,
      "description": "order_token returned by create_order"
    }
  },
  "required": [
    "order_id",
    "order_token"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check whether an installed Cypher eSIM can be topped up and list the plans that can be added to it.

{
  "type": "object",
  "properties": {
    "iccid": {
      "type": "string",
      "minLength": 18,
      "maxLength": 26,
      "description": "ICCID of the installed eSIM (18-22 digits, printed in the eSIM settings)"
    }
  },
  "required": [
    "iccid"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a crypto invoice that adds a data plan to an existing eSIM (no new QR, nothing to install). plan_id must come from list_topups for this ICCID. Payment and polling work exactly like create_order.

{
  "type": "object",
  "properties": {
    "iccid": {
      "type": "string",
      "minLength": 18,
      "maxLength": 26,
      "description": "ICCID of the installed eSIM (18-22 digits, printed in the eSIM settings)"
    },
    "plan_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 80,
      "description": "plan_id from list_plans"
    },
    "coin": {
      "type": "string",
      "minLength": 2,
      "maxLength": 10,
      "description": "Coin code from list_payment_coins, e.g. \"USDT\", \"BTC\", \"XMR\""
    },
    "network": {
      "type": "string",
      "minLength": 2,
      "maxLength": 40,
      "description": "Network from list_payment_coins, e.g. \"tron\", \"solana\". Required for USDT (several networks)."
    }
  },
  "required": [
    "iccid",
    "plan_id",
    "coin"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}