₦Naira Exchange · Dev Docs

📘 API Reference

Logical contracts consumed by the mobile app's services/api/*.api.ts layer (see config/endpoints.ts). Paths are relative to EXPO_PUBLIC_API_BASE_URL.

Auth

MethodPathDescription
POST/auth/registerCreate an account (first/last name, email, password, optional referral code).
POST/auth/loginEmail + password login → access + refresh token.
POST/auth/googleExchanges a Google OAuth/OIDC id token for a session.
POST/auth/forgot-passwordSends a reset email.
POST/auth/reset-passwordCompletes the reset with a token + new password.
POST/auth/refreshExchanges a refresh token for a new access token.
POST/auth/logoutInvalidates the current session server-side.

Profile & User

MethodPathDescription
GET/user/profileCurrent user profile.
PATCH/user/profile/updateUpdate name / phone number.
POST/user/profile/photoMultipart upload of a profile photo.
GET/user/profile/setup-progressAccount-completion percentage + remaining steps.
POST/account/deleteRequests account deletion with a reason.

Wallet

MethodPathDescription
GET/wallet/balanceNGN and USD balances.
GET/wallet/transactionsPaginated history, filterable by type.
GET/wallet/transactions/:idSingle transaction detail.
POST/wallet/withdrawWithdraw to a saved bank account.
POST/wallet/transferTransfer to another user.

Trade

MethodPathDescription
GET/trade/assetsAll supported crypto assets, with price / 24h change / market cap.
GET/trade/assets/:idAsset detail incl. 24h high/low/volume.
POST/trade/quoteLocks a rate + fee for an amount, expires after 30s.
POST/trade/buyExecutes a buy against a quote. Idempotent via clientTransactionId.
POST/trade/sellExecutes a sell. Idempotent.
POST/trade/swapAsset-to-asset swap.

Gift Cards

MethodPathDescription
GET/giftcardsSupported brands + indicative rate per unit.
GET/giftcards/countriesCountries a card can be issued in.
GET/giftcards/historyThe user's past submissions and status.
POST/giftcards/submitMultipart: brand, country, value, notes, front/back images.

KYC · Banks · Referrals · Config

MethodPathDescription
GET/kyc/statusCurrent KYC level + status.
POST/kyc/submitMultipart: document type/image, selfie, address.
GET/banksSaved bank accounts.
POST/banks/validateBank-name-enquiry: account number → account name.
POST/banks/addSaves a validated bank account.
DELETE/banks/:idRemoves a bank account.
GET/referrals/statsReferral code, totals, earnings.
GET/api/mobile/configurationRemote feature flags, nav visibility, currencies, min app version.
POST/notifications/register-tokenRegisters an Expo push token.

Website mock routes

MethodPathDescription
GET/api/assetsMock CryptoAsset[] for the homepage ticker and Rates page.
GET/api/gift-cardsMock GiftCard[] for the Gift Cards page.
GET/api/billsMock BillCategory[] for the Bills Payment page.

Example: login

curl -X POST $API_BASE_URL/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","password":"••••••••"}'
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": { "id": "usr_001", "firstName": "Ada", "kycLevel": 2, "kycStatus": "verified" },
    "tokens": { "accessToken": "…", "refreshToken": "…" }
  }
}

Standard envelope & errors

// success
{ "success": true, "message": "…", "data": { } }

// error
{ "success": false, "message": "Insufficient balance", "code": "INSUFFICIENT_BALANCE", "errors": [] }

The mobile client normalizes every error through services/api/client.ts before it reaches a screen — raw HTTP codes are never shown to the user.