Developer API v1

Geerok Developer API

Integrate Geerok's crypto exchange infrastructure into your platform. Sell crypto to your users using our API.

Base URL

https://geerok.name.ng

Authentication

Session cookie (httpOnly)

Response Format

JSON — all responses

Authentication

Geerok uses session-based authentication with httpOnly cookies. To make authenticated requests:

Call POST /api/auth/sign-in with email and password
The server sets a secure session cookie automatically
Include the cookie in all subsequent requests
Use credentials: "include" in fetch calls

// Example: Sign in and make authenticated request
const login = await fetch("https://geerok.name.ng/api/auth/sign-in", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com", password: "password" })
})

// Then all subsequent calls
const wallet = await fetch("https://geerok.name.ng/api/user/wallet", {
  credentials: "include"
})
const { balance } = await wallet.json()
console.log("Balance:", balance) // e.g. 25000

Error Handling

All errors return a JSON body with an error field and an appropriate HTTP status code.

// Error response format
{ "error": "Human-readable error message" }

// Common status codes:
// 400 — Bad request (missing/invalid fields)
// 401 — Unauthorized (not signed in)
// 400 — Insufficient balance
// 503 — Exchange temporarily unavailable (balance refunded)
// 500 — Internal server error

Authentication

POST/api/auth/sign-up

Create a new user account

REQUEST BODY

{ "email": "user@example.com", "password": "min8chars", "fullName": "John Doe", "phone": "+234..." }

RESPONSE

{ "success": true, "message": "Verification email sent", "needsVerification": true }

POST/api/auth/sign-in

REQUEST BODY

{ "email": "user@example.com", "password": "yourpassword" }

RESPONSE

{ "success": true, "user": { "id": 1, "email": "user@example.com" } }

POST/api/auth/sign-out Auth required

Destroy current session

RESPONSE

{ "success": true }

POST/api/auth/forgot-password

Send password reset email

REQUEST BODY

{ "email": "user@example.com" }

RESPONSE

{ "success": true }

POST/api/auth/reset-password

Reset password with token

REQUEST BODY

{ "token": "reset_token", "password": "newpassword" }

RESPONSE

{ "success": true }

Wallet & Prices

GET/api/user/wallet Auth required

Get authenticated user wallet balance

RESPONSE

{ "balance": 25000.00 }

GET/api/user/price?symbol=BTC Auth required

Get live Naira price for any token

RESPONSE

{ "symbol": "BTC", "naira_price": 98500000, "usdt_price": 61562, "provider": "P3", "usd_ngn_rate": 1600, "spread_percent": 2.5 }

GET/api/user/settings

Get public platform settings

RESPONSE

{ "usd_ngn_rate": "1600", "min_deposit_naira": "5000", "kyc_basic_price": "2000" }

Orders

POST/api/user/buy-crypto Auth required

Place a crypto buy order. Deducts wallet balance immediately. Auto-refunds on failure within 5 minutes.

REQUEST BODY

{ "tokenSymbol": "BTC", "nairaAmount": 50000, "walletAddress": "bc1q..." }

RESPONSE

{ "success": true, "orderId": 42, "orderNumber": "GRK-1234567" }

GET/api/user/otc-tokens Auth required

List all available Peer Exchange tokens

RESPONSE

{ "tokens": [{ "id": 1, "name": "Pi Network", "ticker": "PI", "price_naira": 9000, "allow_buy": true, "allow_sell": true }] }

POST/api/user/otc-order Auth required

Place a Peer Exchange buy or sell order

REQUEST BODY

{ "tokenId": 1, "nairaAmount": 5000, "walletAddress": "pi_address", "type": "buy" }

RESPONSE

{ "success": true, "orderId": 43, "orderNumber": "GRK-OTC-1234567" }

Deposits

GET/api/user/deposit-info

Get bank accounts and deposit settings (public)

RESPONSE

{ "bank_accounts": "[{...}]", "min_deposit": "5000", "deposit_fee_percent": "0" }

POST/api/user/deposit Auth required

Submit a deposit request after bank transfer

REQUEST BODY

{ "amount_naira": 10000, "bank_name": "GTB", "reference": "TXN123456" }

RESPONSE

{ "success": true }

Notifications

GET/api/user/notifications Auth required

Get user notifications and unread count

RESPONSE

{ "notifications": [...], "unreadCount": 3 }

POST/api/user/notifications Auth required

Mark all notifications as read

RESPONSE

{ "success": true }

KYC & Support

GET/api/user/kyc-tickets Auth required

List user KYC support tickets

RESPONSE

{ "tickets": [...] }

POST/api/user/kyc-tickets Auth required

Submit a new KYC support ticket (deducts wallet)

REQUEST BODY

{ "problemType": "Liveness check failed", "platform": "Bybit", "description": "...", "tier": "basic" }

RESPONSE

{ "success": true, "ticket": {...} }

GET/api/user/sidra-appointments Auth required

List user Sidra appointments

RESPONSE

{ "appointments": [...] }

POST/api/user/sidra-appointments Auth required

Book a Sidra verification appointment

REQUEST BODY

{ "username": "sidra_user", "phone": "+234...", "preferred_date": "2026-02-20", "preferred_time": "10:00 AM", "notes": "..." }

RESPONSE

{ "success": true, "appointment": {...} }

Profile

GET/api/user/profile Auth required

Get authenticated user profile

RESPONSE

{ "user": { "full_name": "John", "email": "john@example.com", "phone": "..." } }

POST/api/user/profile Auth required

Update user profile

REQUEST BODY

{ "full_name": "John Doe", "phone": "+234..." }

RESPONSE

{ "success": true }

POST/api/user/change-password Auth required

Change user password

REQUEST BODY

{ "currentPassword": "old", "newPassword": "new8chars" }

RESPONSE

{ "success": true }

Rate Limits & Usage

• Price endpoint: 60 requests/minute per user
• Order endpoints: 10 requests/minute per user
• Authentication: 5 attempts/minute per IP
• All other endpoints: 120 requests/minute per user

To integrate Geerok into your platform or for higher limits, contact us at developers@geerok.name.ng

Ready to integrate?

Create a free account to get started with the API.

Create Account Contact Us

Developer API v1

Geerok Developer API

Integrate Geerok's crypto exchange infrastructure into your platform. Sell crypto to your users using our API.

Base URL

https://geerok.name.ng

Authentication

Session cookie (httpOnly)

Response Format

JSON — all responses

Authentication

Geerok uses session-based authentication with httpOnly cookies. To make authenticated requests:

Call POST /api/auth/sign-in with email and password
The server sets a secure session cookie automatically
Include the cookie in all subsequent requests
Use credentials: "include" in fetch calls

// Example: Sign in and make authenticated request
const login = await fetch("https://geerok.name.ng/api/auth/sign-in", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com", password: "password" })
})

// Then all subsequent calls
const wallet = await fetch("https://geerok.name.ng/api/user/wallet", {
  credentials: "include"
})
const { balance } = await wallet.json()
console.log("Balance:", balance) // e.g. 25000

Error Handling

All errors return a JSON body with an error field and an appropriate HTTP status code.

// Error response format
{ "error": "Human-readable error message" }

// Common status codes:
// 400 — Bad request (missing/invalid fields)
// 401 — Unauthorized (not signed in)
// 400 — Insufficient balance
// 503 — Exchange temporarily unavailable (balance refunded)
// 500 — Internal server error

Authentication

POST/api/auth/sign-up

Create a new user account

REQUEST BODY

{ "email": "user@example.com", "password": "min8chars", "fullName": "John Doe", "phone": "+234..." }

RESPONSE

{ "success": true, "message": "Verification email sent", "needsVerification": true }

POST/api/auth/sign-in

REQUEST BODY

{ "email": "user@example.com", "password": "yourpassword" }

RESPONSE

{ "success": true, "user": { "id": 1, "email": "user@example.com" } }

POST/api/auth/sign-out Auth required

Destroy current session

RESPONSE

{ "success": true }

POST/api/auth/forgot-password

Send password reset email

REQUEST BODY

{ "email": "user@example.com" }

RESPONSE

{ "success": true }

POST/api/auth/reset-password

Reset password with token

REQUEST BODY

{ "token": "reset_token", "password": "newpassword" }

RESPONSE

{ "success": true }

Wallet & Prices

GET/api/user/wallet Auth required

Get authenticated user wallet balance

RESPONSE

{ "balance": 25000.00 }

GET/api/user/price?symbol=BTC Auth required

Get live Naira price for any token

RESPONSE

{ "symbol": "BTC", "naira_price": 98500000, "usdt_price": 61562, "provider": "P3", "usd_ngn_rate": 1600, "spread_percent": 2.5 }

GET/api/user/settings

Get public platform settings

RESPONSE

{ "usd_ngn_rate": "1600", "min_deposit_naira": "5000", "kyc_basic_price": "2000" }

Orders

POST/api/user/buy-crypto Auth required

Place a crypto buy order. Deducts wallet balance immediately. Auto-refunds on failure within 5 minutes.

REQUEST BODY

{ "tokenSymbol": "BTC", "nairaAmount": 50000, "walletAddress": "bc1q..." }

RESPONSE

{ "success": true, "orderId": 42, "orderNumber": "GRK-1234567" }

GET/api/user/otc-tokens Auth required

List all available Peer Exchange tokens

RESPONSE

{ "tokens": [{ "id": 1, "name": "Pi Network", "ticker": "PI", "price_naira": 9000, "allow_buy": true, "allow_sell": true }] }

POST/api/user/otc-order Auth required

Place a Peer Exchange buy or sell order

REQUEST BODY

{ "tokenId": 1, "nairaAmount": 5000, "walletAddress": "pi_address", "type": "buy" }

RESPONSE

{ "success": true, "orderId": 43, "orderNumber": "GRK-OTC-1234567" }

Deposits

GET/api/user/deposit-info

Get bank accounts and deposit settings (public)

RESPONSE

{ "bank_accounts": "[{...}]", "min_deposit": "5000", "deposit_fee_percent": "0" }

POST/api/user/deposit Auth required

Submit a deposit request after bank transfer

REQUEST BODY

{ "amount_naira": 10000, "bank_name": "GTB", "reference": "TXN123456" }

RESPONSE

{ "success": true }

Notifications

GET/api/user/notifications Auth required

Get user notifications and unread count

RESPONSE

{ "notifications": [...], "unreadCount": 3 }

POST/api/user/notifications Auth required

Mark all notifications as read

RESPONSE

{ "success": true }

KYC & Support

GET/api/user/kyc-tickets Auth required

List user KYC support tickets

RESPONSE

{ "tickets": [...] }

POST/api/user/kyc-tickets Auth required

Submit a new KYC support ticket (deducts wallet)

REQUEST BODY

{ "problemType": "Liveness check failed", "platform": "Bybit", "description": "...", "tier": "basic" }

RESPONSE

{ "success": true, "ticket": {...} }

GET/api/user/sidra-appointments Auth required

List user Sidra appointments

RESPONSE

{ "appointments": [...] }

POST/api/user/sidra-appointments Auth required

Book a Sidra verification appointment

REQUEST BODY

{ "username": "sidra_user", "phone": "+234...", "preferred_date": "2026-02-20", "preferred_time": "10:00 AM", "notes": "..." }

RESPONSE

{ "success": true, "appointment": {...} }

Profile

GET/api/user/profile Auth required

Get authenticated user profile

RESPONSE

{ "user": { "full_name": "John", "email": "john@example.com", "phone": "..." } }

POST/api/user/profile Auth required

Update user profile

REQUEST BODY

{ "full_name": "John Doe", "phone": "+234..." }

RESPONSE

{ "success": true }

POST/api/user/change-password Auth required

Change user password

REQUEST BODY

{ "currentPassword": "old", "newPassword": "new8chars" }

RESPONSE

{ "success": true }

Rate Limits & Usage

• Price endpoint: 60 requests/minute per user
• Order endpoints: 10 requests/minute per user
• Authentication: 5 attempts/minute per IP
• All other endpoints: 120 requests/minute per user

To integrate Geerok into your platform or for higher limits, contact us at developers@geerok.name.ng

Ready to integrate?

Create a free account to get started with the API.

Create Account Contact Us