Scopes

Scopes are permissions your app requests from the user. Each scope unlocks a specific group of API endpoints. Request only what your app genuinely needs, users are more likely to approve a minimal, specific request than a broad one.

Scope reference

Scope	What it allows	Sensitive
`profile:read`	Read the user’s name and account details	No
`kyc:read`	Check the user’s KYC verification tier and transaction limits	No
`wallet:read`	View NGN and crypto wallet balances, portfolios, transaction history	No
`wallet:deposit`	Initiate a deposit into the user’s wallet	No
`wallet:send`	Send money to other Monei users (peer-to-peer)	Yes
`wallet:withdraw`	Withdraw NGN to a bank account	Yes
`swap:execute`	Execute crypto token swaps and send crypto on EVM / Solana	Yes
`bills:pay`	Discover billers, validate bills, and pay airtime, data, electricity, and cable TV	No
`offramp:execute`	Get offramp quotes, convert crypto to NGN, track offramp transactions	Yes
`escrow:create`	Hold funds from the user’s wallet in escrow	Yes
`escrow:release`	Release held escrow funds to the payee	Yes
`escrow:refund`	Return held escrow funds to the payer	Yes
`escrow:dispute`	Flag a held escrow as disputed	Yes
`escrow:read`	View escrow transaction status and history	No

Sensitive scopes move or convert real money. Monei displays an extra warning to users when a sensitive scope is requested. If your app only needs to read data, stick to non-sensitive scopes, you’ll see significantly higher approval rates.

Endpoints unlocked per scope

`profile:read`

GET /api/v1/user/me

`kyc:read`

GET /api/v1/kyc/status
GET /api/v1/kyc/limits

`wallet:read`

GET /api/v1/wallet/me
GET /api/v1/wallet/naira-wallet
GET /api/v1/transactions
GET /api/v1/wallet/deposit/status/:reference
GET /api/v1/evm/portfolio/:chainId
GET /api/v1/evm/balance/native
GET /api/v1/evm/balance/token
GET /api/v1/solana/portfolio
GET /api/v1/solana/balance
GET /api/v1/solana/address
GET /api/v1/bills/records
GET /api/v1/offramp/ledger/history
GET /api/v1/offramp/ledger/status/:reference

`wallet:deposit`

POST /api/v1/wallet/deposit
POST /api/v1/wallet/deposit/payment-link

`wallet:send`

POST /api/v1/wallet/payout/transfer

`wallet:withdraw`

POST /api/v1/wallet/payout/bank-transfer

`swap:execute`

POST /api/v1/evm-exchange/native-to-token
POST /api/v1/evm-exchange/token-to-token
POST /api/v1/evm-exchange/token-to-native
POST /api/v1/solana-exchange/swap-sol-to-token
POST /api/v1/solana-exchange/swap-token-to-token
POST /api/v1/solana-exchange/swap-token-to-sol
POST /api/v1/evm/send/native
POST /api/v1/evm/send/token
POST /api/v1/solana/transfer
POST /api/v1/solana/transfer-token

`bills:pay`

GET  /api/v1/bills/discovery/categories
POST /api/v1/bills/validation/customer
POST /api/v1/bills/pay/airtime
POST /api/v1/bills/pay/data
POST /api/v1/bills/pay/electricity
POST /api/v1/bills/pay/cable-tv

`offramp:execute`

GET  /api/v1/offramp/exchange/assets
GET  /api/v1/offramp/exchange/quote
POST /api/v1/offramp/exchange/initiate

`escrow:create`

POST /api/v1/escrow/hold

`escrow:release`

POST /api/v1/escrow/:id/release

`escrow:refund`

POST /api/v1/escrow/:id/refund

`escrow:dispute`

POST /api/v1/escrow/:id/dispute

Resolving a dispute (POST /api/v1/escrow/:id/resolve) is not included, that endpoint is admin-only and isn’t reachable via any Connect scope. See Escrow → Disputes.

`escrow:read`

GET /api/v1/escrow/:id
GET /api/v1/escrow/mine/paying
GET /api/v1/escrow/mine/receiving
GET /api/v1/escrow/mine/pending-incoming

Requesting scopes

Pass scopes as a space-separated string in the authorization URL:

scope=wallet:read profile:read
scope=wallet:read wallet:send wallet:withdraw
scope=wallet:read bills:pay offramp:execute
scope=wallet:read escrow:create escrow:release escrow:refund

Scope best practices

Ask for the minimum. Only request scopes your app needs right now. You can always request additional scopes later by sending the user through the authorization flow again. Monei will show only the new scopes being requested. Group related scopes. If your app reads balances and pays bills, request wallet:read and bills:pay together. Don’t request wallet:withdraw unless withdrawal is a core feature. Explain sensitive scopes. If you need wallet:withdraw or swap:execute, tell users why in your app’s UI before redirecting to Monei. Informed users approve more. Handle partial grants. Even with minimal scope requests, users may decline individual scopes. See Partial Grants for how to handle this.

Partial Grants →

Users can approve fewer scopes than you request. Here’s how to handle that gracefully.

Escrow →

Deep dive into the escrow scopes, hold funds and release them on your own confirmation logic.

Overview

Getting Started

Authorization

Token Management

Features

Reference

Scope reference

Endpoints unlocked per scope

`profile:read`

`kyc:read`

`wallet:read`

`wallet:deposit`

`wallet:send`

`wallet:withdraw`

`swap:execute`

`bills:pay`

`offramp:execute`

`escrow:create`

`escrow:release`

`escrow:refund`

`escrow:dispute`

`escrow:read`

Requesting scopes

Scope best practices

Partial Grants →

Escrow →

​Scope reference

​Endpoints unlocked per scope

​profile:read

​kyc:read

​wallet:read

​wallet:deposit

​wallet:send

​wallet:withdraw

​swap:execute

​bills:pay

​offramp:execute

​escrow:create

​escrow:release

​escrow:refund

​escrow:dispute

​escrow:read

​Requesting scopes

​Scope best practices

Partial Grants →

Escrow →

Scope reference

Endpoints unlocked per scope

`profile:read`

`kyc:read`

`wallet:read`

`wallet:deposit`

`wallet:send`

`wallet:withdraw`

`swap:execute`

`bills:pay`

`offramp:execute`

`escrow:create`

`escrow:release`

`escrow:refund`

`escrow:dispute`

`escrow:read`

Requesting scopes

Scope best practices