The Numpay API is a JSON REST API. It manages the identity directory (phone/email ↔ wallet), payment history, requests and NEAR deposits. It never moves a registered user’s funds; payments are signed and sent by the client. An API client calls the Numpay API and receives a JSON response. An API client calls the Numpay API and receives a JSON response.

​
Base URL

All paths in this reference are relative to /api.

​
Conventions

  • Request and response bodies are JSON (Content-Type: application/json).
  • IDs are UUID v4 strings.
  • Phone numbers are E.164 (+14155550123). Spaces and dashes are stripped by the server. URL-encode the leading + as %2B in paths.
  • Emails are case-insensitive and stored lowercased. URL-encode @ as %40 in paths.
  • Amounts are decimal USDC numbers (12.5), except NEAR deposit amounts, which are decimal strings ("12.50").
  • Wallet addresses are 42-character hex strings and always refer to the user’s Kernel smart account.

​
Rate limits

100 requests per minute per IP across all /api routes. Exceeding it returns 429 Too Many Requests with the body Too many requests, please try again later.

​
CORS

Browser calls are accepted only from Numpay’s own web origins in production (https://app.numpay.app, https://numpay.app). Server-to-server calls aren’t affected by CORS.

​
Endpoint index

Required means the endpoint requires a Bearer token.

​
Health check

GET https://api.numpay.app/ returns the plain-text body Welcome to the Numpay API.