Accounts

List accounts

GET /accounts

Returns all accounts you have provisioned, sorted newest first.

Query parameters:

Parameter	Default	Description
limit	20	Results per page (max 100)
page	1	Page number

Response:

{
  "total_count": 2,
  "page": 1,
  "limit": 20,
  "accounts": [
    {
      "account_id": "3f8a1b2c-...",
      "status": "active",
      "external_user_id": "your-internal-user-id",
      "yield_enabled": false,
      "created_at": "2026-07-21T10:00:00Z"
    }
  ]
}

---

Create an account

POST /accounts

Creates a Regini USDC account for one of your users. Returns an account_id that you store on your side and use for all subsequent API calls.

This call is idempotent on your external_user_id — calling it twice for the same user returns the same account_id.

Request:

{
  "external_user_id": "your-internal-user-id",
  "phone": "+254700000000",
  "first_name": "Jane",
  "last_name": "Doe",
  "program_id": "your-program-uuid",
  "kyc_status": "verified"
}

Field	Required	Description
external_user_id	Yes	Your internal user identifier. Used for idempotency.
phone	Yes	E.164 format (e.g. +254700000000). Used for M-Pesa.
first_name	Yes	User's first name
last_name	Yes	User's last name
program_id	Yes	Your Regini program UUID (provided during onboarding)
kyc_status	No	Defaults to "verified". Pass "verified" when your user has passed KYC.

Response:

{
  "account_id": "3f8a1b2c-...",
  "created": true
}

Field	Description
account_id	Store this — used for all subsequent calls
created	true if a new account was provisioned; false if the external_user_id was already registered (idempotent return)

Wallet provisioning

The account is immediately active for KES deposits and withdrawals. A Turnkey sub-org (on-chain wallet) is provisioned asynchronously in the background. Check wallet_provisioning_status via GET /accounts/{account_id} if you need to verify wallet readiness. In sandbox, the wallet is marked active immediately — no async step.

---

Get account details

GET /accounts/{account_id}

Returns account status and the stored user profile.

{
  "account_id": "3f8a1b2c-...",
  "status": "active",
  "wallet_provisioning_status": "active",
  "yield_enabled": false,
  "user": {
    "external_user_id": "your-internal-user-id",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone_number": "+254700000000",
    "kyc_verified": true
  }
}

Field	Description
status	Account status: active, inactive, or suspended
wallet_provisioning_status	pending, active, or failed — tracks on-chain wallet setup
yield_enabled	Whether the account participates in yield pools (Phase 2)