MyOTP.App

Send a one-time password (OTP) to a phone number via SMS, WhatsApp, or Telegram. MyOTP.App generates the code, formats the message, picks the best carrier route, and delivers it. Returns a `message_id` (UUID) — keep it; you'll pass it to `verify_otp`, `check_otp_status`, or `extend_otp` later. Each call deducts credits from the account balance; the per-message cost varies by destination country and channel and is returned in the `cost` field. Use this whenever an app needs to verify someone's phone — signup, login 2FA, password reset, transaction confirmation, etc.

{
  "type": "object",
  "properties": {
    "phone_number": {
      "type": "string",
      "minLength": 7,
      "maxLength": 15,
      "pattern": "^[1-9]\\d{6,14}$",
      "description": "Destination phone number in international format with NO leading + or 0. Must be 7-15 digits and start with a non-zero digit. Example: '14155551234' for a US number, '447911123456' for a UK number."
    },
    "channel": {
      "type": "string",
      "enum": [
        "sms",
        "whatsapp",
        "telegram"
      ],
      "description": "Delivery channel. 'sms' (default) works in 190+ countries. 'whatsapp' is best for India/Brazil/Indonesia/Mexico/Nigeria/Turkey. 'telegram' is best for privacy-focused users. Same API for all three."
    },
    "otp_length": {
      "type": "integer",
      "minimum": 3,
      "maximum": 8,
      "description": "Number of digits in the auto-generated OTP. Range 3-8 (4-8 for telegram). Default 6. Requires CUSTOM_OTP_LENGTH entitlement (Business plan or above)."
    },
    "otp_code": {
      "type": "string",
      "pattern": "^\\d{3,8}$",
      "description": "Provide your own pre-generated numeric OTP code (3-8 digits, 4-8 for telegram) instead of letting MyOTP generate one. Useful when you already have a code from another system."
    },
    "otp_validity": {
      "type": "integer",
      "minimum": 30,
      "maximum": 14400,
      "description": "How long the OTP stays valid, in seconds. Range 30-14400 (30-3600 for telegram). Default 300 (5 minutes). Requires CUSTOM_OTP_EXPIRY entitlement (Business plan or above)."
    },
    "brand": {
      "type": "string",
      "minLength": 3,
      "maxLength": 16,
      "pattern": "^[a-zA-Z0-9.]+$",
      "description": "Sender brand name shown to the recipient (3-16 alphanumeric characters plus dots). Defaults to the brand registered against the API key, or 'MyOTP.App' if none."
    },
    "return_otp": {
      "type": "boolean",
      "description": "If true, the API response will include the generated OTP code in plain text. Useful for testing or when you want to deliver the OTP via your own channel. Defaults to false. SECURITY: never enable this in production user flows."
    },
    "force_send": {
      "type": "boolean",
      "description": "If true, send a new OTP even if one is already active for this phone number. By default the API returns 409 in that case. Use sparingly — repeated sends to the same number can hit carrier-level spam filters."
    },
    "template_order": {
      "type": "integer",
      "minimum": 1,
      "maximum": 99,
      "description": "Pick a specific message template by its order number (1-99). WhatsApp has four: 12 (English, 5-minute code), 13 (English, 10 minutes), 14 (Spanish es_MX, 5 minutes), 15 (Spanish es_MX, 10 minutes). On WhatsApp the template's own expiry overrides otp_validity. Requires the ACCESS_TO_TEMPLATES entitlement (Business plan and up). Not supported on telegram (Telegram generates its own message text)."
    }
  },
  "required": [
    "phone_number"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "description": "ID of the message sent. Pass it to verify_otp, check_otp_status and extend_otp."
    },
    "status": {
      "type": "string",
      "description": "Always 'accepted' on success; delivery state comes from check_otp_status."
    },
    "message": {
      "type": "string",
      "description": "Message describing the status of the request."
    },
    "date_sent": {
      "type": "string",
      "description": "ISO 8601 date-time the OTP was sent."
    },
    "expires_at": {
      "type": "string",
      "description": "ISO 8601 date-time the OTP expires."
    },
    "cost": {
      "type": "number",
      "description": "Credits charged for this send."
    },
    "otp": {
      "type": "string",
      "description": "The OTP value, present only when return_otp was true."
    }
  },
  "required": [
    "message_id",
    "status",
    "message",
    "date_sent",
    "expires_at",
    "cost"
  ],
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Verify a code submitted by an end user against the OTP MyOTP delivered. Returns `{status: 'success'}` if the code matches and the OTP hasn't expired — at that point the OTP is consumed and cannot be reused. Returns `{status: 'failed', reason: 'invalid' | 'expired' | 'not found'}` otherwise. You MUST pass either `phone_number` or `message_id` to identify which OTP you're verifying against. Call this after collecting the code from the user (login form, signup screen, etc.).

{
  "type": "object",
  "properties": {
    "otp": {
      "type": "string",
      "pattern": "^\\d{3,8}$",
      "description": "The OTP code the end user typed in (3-8 numeric digits). This is the code you're trying to verify against what was sent."
    },
    "phone_number": {
      "type": "string",
      "pattern": "^[1-9]\\d{6,14}$",
      "description": "Phone number the OTP was originally sent to, in international format without + or leading 0. Provide either this OR `message_id` — `message_id` is more precise."
    },
    "message_id": {
      "type": "string",
      "format": "uuid",
      "description": "The UUID returned by `generate_otp`. Provide either this OR `phone_number`. Prefer this when you have it — it disambiguates if the same number got multiple OTPs."
    }
  },
  "required": [
    "otp"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "'success' when the code matched and the OTP was consumed, otherwise 'failed' (or 'expired')."
    },
    "message": {
      "type": "string",
      "description": "Message describing the verification result."
    },
    "reason": {
      "type": "string",
      "description": "Why verification failed: 'invalid', 'expired' or 'not found'. Absent on success."
    }
  },
  "required": [
    "status",
    "message"
  ],
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check whether a previously sent OTP is still active and (with DLR_ACCESS entitlement on Enterprise plan) get its delivery status. Returns `is_active` (bool) and `expires_at` (ISO timestamp) on every plan. On Enterprise plans, also returns `DLR`: 'delivered', 'sent', 'read', 'pending', or a failure as `failed.<reason>` (on WhatsApp, `failed.Undeliverable` means the number cannot receive WhatsApp and `failed.Provider` means a retry is worth it). Useful when an end user reports they didn't receive the code — you can confirm whether MyOTP delivered it before deciding to resend. Does NOT verify a code; use `verify_otp` for that.

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "format": "uuid",
      "description": "The UUID returned by `generate_otp` — this identifies which OTP you want a status report on."
    }
  },
  "required": [
    "message_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "DLR": {
      "type": "string",
      "description": "Delivery state: carrier status (ATES, DELIVRD, UNDELIV, EXPIRED, REJECTD) or sent/delivered/read/pending/failed.<reason>, a 'Pending: ...' hint, or a 'Not available ...' explanation. Absent when the message_id is unknown."
    },
    "is_active": {
      "type": "boolean",
      "description": "Whether the OTP can still be verified (it has not expired)."
    },
    "expires_at": {
      "type": "string",
      "description": "ISO 8601 date-time the OTP expires. Absent when the message_id is unknown."
    },
    "message": {
      "type": "string",
      "description": "Present instead of DLR when the message_id is not found."
    },
    "DLR:": {
      "type": "string",
      "description": "Deprecated alias of DLR."
    },
    "Message:": {
      "type": "string",
      "description": "Deprecated alias of message."
    }
  },
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Extend the expiry time of an active OTP without sending a new one. Useful when the end user is taking longer than expected to enter the code (e.g., switched apps, dealing with carrier delivery delay). Adds `duration` seconds (60-14400) to the current `expires_at`. Requires the EXTEND_OTP entitlement (Business or Enterprise plan). Some destination countries don't allow extensions — the API will return 403 in that case. Cheaper and less spammy than calling `generate_otp` again.

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "format": "uuid",
      "description": "The UUID returned by `generate_otp` — identifies the OTP you want to extend."
    },
    "duration": {
      "type": "integer",
      "minimum": 60,
      "maximum": 14400,
      "description": "Additional seconds to add to the OTP's expiry. Range 60-14400 (1 minute to 4 hours). The new expiry will be the current expiry + this duration."
    }
  },
  "required": [
    "message_id",
    "duration"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Status of the request."
    },
    "message": {
      "type": "string",
      "description": "Message describing the result."
    },
    "expires_at": {
      "type": "string",
      "description": "The new ISO 8601 expiry date-time."
    }
  },
  "required": [
    "status",
    "message",
    "expires_at"
  ],
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return account details for the API key in use. Always returns at least the account `email`; depending on plan and platform version may also return balance/credit/plan info. Use this as a sanity check when wiring up MyOTP for the first time — if this call succeeds, your API key and IP whitelist are configured correctly.

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

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Email address of the account the API key belongs to."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch a paginated list of OTP transactions for a date range. Each transaction includes message_id, timestamp, phone_number, channel, country, cost, status, and the originating client IP. Date range cannot exceed 31 days. Defaults: last 7 days, page 1, 10 per page. Requires the API_REPORTING entitlement (Business or Enterprise plan). Use this to: audit recent activity, build internal dashboards, reconcile billing, or debug delivery issues across many recipients.

{
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start date in YYYY-MM-DD format (UTC). If omitted, defaults to 7 days before today. The range start_date..end_date cannot exceed 31 days."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "End date in YYYY-MM-DD format (UTC). If omitted, defaults to today. The range start_date..end_date cannot exceed 31 days."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "Page number for paginated results, starting at 1. Default 1."
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Results per page, 1-100. Default 10."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "total_count": {
      "type": "integer",
      "description": "Total transactions matching the date range."
    },
    "total_pages": {
      "type": "integer",
      "description": "Number of pages at the requested per_page."
    },
    "current_page": {
      "type": "integer",
      "description": "The page returned."
    },
    "per_page": {
      "type": "integer",
      "description": "Rows per page."
    },
    "transactions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "message_id": {
            "type": "string"
          },
          "message_timestamp": {
            "type": "string",
            "description": "ISO 8601 date-time of the transaction."
          },
          "message_type": {
            "type": "integer",
            "description": "Whether this was an OTP send or a verification."
          },
          "phone_number": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "description": "sms, whatsapp or telegram."
          },
          "country": {
            "type": "string"
          },
          "force_send": {
            "type": "boolean"
          },
          "application": {
            "type": [
              "string",
              "null"
            ]
          },
          "cost": {
            "type": "number",
            "description": "Credits charged."
          },
          "status": {
            "type": "string",
            "description": "Transaction status, e.g. delivered, read, failed.NoBalance."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "client_ip": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "description": "Transaction rows for the page. May be empty or absent when there is no data."
    },
    "message": {
      "type": "string",
      "description": "Present when the endpoint has no data for the range."
    }
  },
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a MyOTP.App agent account and return its one-time API key. No API key is required for this tool. The new account starts with zero balance; USDC top-ups work immediately, while card top-ups unlock after a human confirms the email address.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "Email address for the new MyOTP.App account."
    },
    "name": {
      "type": "string",
      "maxLength": 64,
      "description": "Optional account, company, or product name (maximum 64 characters)."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account identifier, 'a' followed by 12 hex characters."
    },
    "api_key": {
      "type": "string",
      "description": "The API key. Shown once, in this response only. Send it as the X-API-Key header."
    },
    "api_key_note": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "email_verified": {
      "type": "boolean",
      "description": "True once the human has confirmed the emailed link. Unlocks card top-ups."
    },
    "balance": {
      "type": "number",
      "description": "Credits on the balance. Zero at registration."
    },
    "plan_id": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "description": "Account status, 'active' when the key can be used."
    },
    "topup": {
      "type": "object",
      "properties": {
        "quote": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      },
      "additionalProperties": true,
      "description": "Where to buy credits."
    },
    "docs": {
      "type": "string"
    },
    "verification_email_sent": {
      "type": "boolean",
      "description": "Whether the confirmation email was queued."
    }
  },
  "required": [
    "account_id",
    "api_key",
    "email",
    "email_verified",
    "balance",
    "plan_id",
    "status"
  ],
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return email verification, balance, plan, and status for the configured MyOTP agent account. Set resend_verification to request another confirmation email first. Unverified accounts can top up with USDC, but cards stay locked.

{
  "type": "object",
  "properties": {
    "resend_verification": {
      "type": "boolean",
      "description": "Send another confirmation email before returning account status."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "email_verified": {
      "type": "boolean",
      "description": "True once the human has confirmed the emailed link. Unlocks card top-ups."
    },
    "balance": {
      "type": "number",
      "description": "Credits on the balance."
    },
    "plan_id": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "description": "Account status, 'active' when the key can be used."
    },
    "hint": {
      "type": "string",
      "description": "What to do next: verify the email, top up, or start sending."
    }
  },
  "required": [
    "email_verified",
    "balance",
    "plan_id",
    "status",
    "hint"
  ],
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get the live price and payment options for buying MyOTP credits, without making a purchase. Use this when generate_otp or another send fails with HTTP 403 insufficient balance / NoBalance, or before calling `top_up_credits` to show the cost. Returns USDC and card client commands and never exposes the configured API key.

{
  "type": "object",
  "properties": {
    "credits": {
      "type": "integer",
      "minimum": 25,
      "maximum": 50000,
      "default": 100,
      "description": "Number of credits to quote. Integer from 25 to 50,000; defaults to 100."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "credits": {
      "type": "integer",
      "description": "The number of credits priced."
    },
    "amount_usd": {
      "type": "string",
      "description": "Total price in US dollars, as a decimal string."
    },
    "price_per_credit_usd": {
      "type": "number",
      "description": "Unit price. Currently 0.02."
    },
    "min_credits": {
      "type": "integer"
    },
    "max_credits": {
      "type": "integer"
    },
    "currency": {
      "type": "string",
      "description": "Always 'usd'."
    },
    "methods": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Human-readable list of the accepted payment methods."
    },
    "rules": {
      "type": "string",
      "description": "Top-up limits: unit price, minimum, maximum and the card cap."
    },
    "how_to_pay": {
      "type": "object",
      "properties": {
        "usdc": {
          "type": "string",
          "description": "mppx command that pays the challenge in USDC on Tempo."
        },
        "card": {
          "type": "string",
          "description": "Stripe Link CLI command that pays the challenge by card."
        }
      },
      "required": [
        "usdc",
        "card"
      ],
      "additionalProperties": true,
      "description": "Ready-to-run client commands for this amount."
    }
  },
  "required": [
    "credits",
    "amount_usd",
    "price_per_credit_usd",
    "min_credits",
    "max_credits",
    "currency",
    "methods",
    "rules",
    "how_to_pay"
  ],
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Prepare or complete an autonomous MyOTP credit purchase with USDC or card through Machine Payments Protocol (MPP). Use this when generate_otp or another send fails with HTTP 403 insufficient balance / NoBalance. The tool quotes first, then returns a structured 402 challenge and exact retry details for the agent's own MPP client; if fetch is already wrapped by a credential-carrying MPP runtime, it returns the credited response directly.

{
  "type": "object",
  "properties": {
    "credits": {
      "type": "integer",
      "minimum": 25,
      "maximum": 50000,
      "description": "Number of credits to buy. Integer from 25 to 50,000."
    },
    "dry_run": {
      "type": "boolean",
      "description": "If true, return only the quote and explanation without requesting a payment challenge."
    }
  },
  "required": [
    "credits"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "quote": {
      "type": "object",
      "properties": {
        "credits": {
          "type": "integer",
          "description": "The number of credits priced."
        },
        "amount_usd": {
          "type": "string",
          "description": "Total price in US dollars, as a decimal string."
        },
        "price_per_credit_usd": {
          "type": "number",
          "description": "Unit price. Currently 0.02."
        },
        "min_credits": {
          "type": "integer"
        },
        "max_credits": {
          "type": "integer"
        },
        "currency": {
          "type": "string",
          "description": "Always 'usd'."
        },
        "methods": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Human-readable list of the accepted payment methods."
        }
      },
      "required": [
        "credits",
        "amount_usd",
        "price_per_credit_usd",
        "min_credits",
        "max_credits",
        "currency",
        "methods"
      ],
      "additionalProperties": true,
      "description": "The quote for the requested credits (dry run and 402 results)."
    },
    "explanation": {
      "type": "string",
      "description": "What happened and what the caller must do next (dry run and 402 results)."
    },
    "challengeId": {
      "type": "string",
      "description": "The MPP challenge id from the 402 response."
    },
    "offers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "method": {
            "type": "string",
            "description": "tempo (USDC) or stripe (card)."
          },
          "intent": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "expires": {
            "type": "string",
            "description": "ISO 8601 expiry of the offer."
          },
          "amount": {
            "type": [
              "string",
              "number"
            ]
          },
          "amount_unit": {
            "type": "string",
            "description": "What amount is denominated in: USDC atomic units for tempo, cents for stripe."
          },
          "amount_usd": {
            "type": "string",
            "description": "amount converted to USD with two decimals when the unit is known."
          },
          "currency": {
            "type": "string"
          }
        },
        "required": [
          "method",
          "intent",
          "id",
          "expires",
          "amount",
          "amount_unit",
          "currency"
        ],
        "additionalProperties": true
      },
      "description": "Decoded Payment offers from the WWW-Authenticate challenge (402 result)."
    },
    "retry": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string"
        },
        "method": {
          "type": "string"
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Headers to send; placeholders mark the API key and payment credential."
        },
        "body": {
          "type": "object",
          "additionalProperties": {}
        }
      },
      "required": [
        "url",
        "method",
        "headers",
        "body"
      ],
      "additionalProperties": true,
      "description": "The request to replay with a payment credential (402 result)."
    },
    "how_to_pay": {
      "type": "object",
      "properties": {
        "usdc": {
          "type": "string",
          "description": "mppx command that pays the challenge in USDC on Tempo."
        },
        "card": {
          "type": "string",
          "description": "Stripe Link CLI command that pays the challenge by card."
        }
      },
      "required": [
        "usdc",
        "card"
      ],
      "additionalProperties": true,
      "description": "Ready-to-run client commands (402 result)."
    },
    "status": {
      "type": "string",
      "description": "'credited' or 'already_credited' (settled result)."
    },
    "credits": {
      "type": "integer",
      "description": "Credits bought in this call (settled result)."
    },
    "amount_usd": {
      "type": "string",
      "description": "Amount paid in US dollars (settled result)."
    },
    "currency": {
      "type": "string"
    },
    "payment": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string"
        },
        "reference": {
          "type": "string"
        }
      },
      "additionalProperties": true,
      "description": "Payment method and reference (settled result)."
    },
    "balance": {
      "type": "number",
      "description": "Account balance in credits after the top-up (settled result)."
    },
    "plan_id": {
      "type": "integer"
    }
  },
  "additionalProperties": true,
  "$schema": "http://json-schema.org/draft-07/schema#"
}