Overview

Stocken API

The Stocken API allows you to integrate STKN wallet operations directly into the Stockoo platform and any authorized third-party application. All endpoints are RESTful and return JSON responses.

Base URL

api.stocken.io/v1

Protocol

HTTPS only

Response Format

JSON

Auth Method

API Key (Header)

Rate Limit

1000 req / hour

Status

● Live · Q3 2026

Auth

Authentication

All API requests must include your API key in the request header. Keep your key secret — never expose it in client-side code.

🔑 API Key Header

Include your API key as X-STKN-API-Key in every request header.

HTTP Header

X-STKN-API-Key: your_api_key_here
Content-Type: application/json

Errors

Error Codes

The API uses standard HTTP status codes. All errors return a JSON body with a code and message field.

Error Response

{
  "success": false,
  "code": "INSUFFICIENT_BALANCE",
  "message": "Wallet does not have enough STKN balance"
}

HTTP Code	Code	Description
200	SUCCESS	Request completed successfully
400	INVALID_PARAMS	Missing or invalid request parameters
401	UNAUTHORIZED	Invalid or missing API key
404	WALLET_NOT_FOUND	Wallet address does not exist
409	WALLET_EXISTS	Wallet already exists for this user
422	INSUFFICIENT_BALANCE	Wallet does not have enough STKN
429	RATE_LIMITED	Too many requests — slow down
500	SERVER_ERROR	Internal server error — contact support

Wallet

Create Wallet

Creates a new STKN wallet for a Stockoo user. Called during user registration. Each user can only have one wallet.

POST https://api.stocken.io/v1/wallet/create

Parameters

Request

Response

Field	Type	Required	Description
user_id	string	required	Unique Stockoo user ID
email	string	required	User's email address
name	string	optional	User's display name

cURL

curl -X POST https://api.stocken.io/v1/wallet/create \
  -H "X-STKN-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_123456",
    "email": "user@stockoo.in",
    "name": "Rahul Sharma"
  }'

200 Created

JSON

{
  "success": true,
  "wallet": {
    "address": "0x4a3b...f9c2",
    "user_id": "usr_123456",
    "balance": 0,
    "created_at": "2026-07-01T10:00:00Z"
  }
}

Wallet

Link Wallet

Links an existing BNB Chain wallet address to a Stockoo user account. Used when a user already has a MetaMask or external wallet.

POST https://api.stocken.io/v1/wallet/link

Parameters

Request

Response

Field	Type	Required	Description
user_id	string	required	Stockoo user ID to link wallet to
address	string	required	BNB Chain wallet address (0x...)
signature	string	required	Signed message proving wallet ownership

cURL

curl -X POST https://api.stocken.io/v1/wallet/link \
  -H "X-STKN-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_123456",
    "address": "0x4a3b9c...f9c2",
    "signature": "0xabc123..."
  }'

200 OK

JSON

{
  "success": true,
  "wallet": {
    "address": "0x4a3b9c...f9c2",
    "user_id": "usr_123456",
    "linked": true,
    "linked_at": "2026-07-01T10:05:00Z"
  }
}

Wallet

Get Balance

Returns the current STKN balance for a given wallet address. Used to display balance in the Stockoo app.

GET https://api.stocken.io/v1/wallet/{address}/balance

Parameters

Request

Response

Field	Type	Required	Description
address	path param	required	BNB Chain wallet address (0x...)

cURL

curl -X GET https://api.stocken.io/v1/wallet/0x4a3b...f9c2/balance \
  -H "X-STKN-API-Key: your_api_key"

200 OK

JSON

{
  "success": true,
  "address": "0x4a3b...f9c2",
  "balance": {
    "stkn": 1250.75,
    "pending_rewards": 45.00,
    "inr_value": 8754.23,
    "updated_at": "2026-07-01T10:10:00Z"
  }
}

Wallet

Mint STKN

Mints accumulated STKN rewards to a user's wallet. Called when a user requests withdrawal of their pending rewards to their on-chain wallet.

POST https://api.stocken.io/v1/wallet/mint

Parameters

Request

Response

Field	Type	Required	Description
address	string	required	Destination wallet address
amount	number	required	Amount of STKN to mint (whole tokens)
user_id	string	required	Stockoo user ID for verification

cURL

curl -X POST https://api.stocken.io/v1/wallet/mint \
  -H "X-STKN-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x4a3b...f9c2",
    "amount": 250,
    "user_id": "usr_123456"
  }'

200 OK

JSON

{
  "success": true,
  "tx_hash": "0xabc123def456...",
  "amount": 250,
  "address": "0x4a3b...f9c2",
  "status": "confirmed",
  "minted_at": "2026-07-01T10:15:00Z"
}

Wallet

Add Reward

Adds STKN reward directly to a user's wallet balance. Called by the Stockoo rewards engine when a user completes a reward-eligible action (login, prediction, referral, etc.).

POST https://api.stocken.io/v1/wallet/reward

Parameters

Request

Response

Field	Type	Required	Description
user_id	string	required	Stockoo user ID receiving the reward
amount	number	required	STKN amount to add as reward
reason	string	required	Reward type: `daily_login \| streak \| prediction \| referral \| community \| top_performer`
reference_id	string	optional	Reference ID for the triggering event (e.g. prediction ID)

cURL

curl -X POST https://api.stocken.io/v1/wallet/reward \
  -H "X-STKN-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_123456",
    "amount": 5,
    "reason": "daily_login",
    "reference_id": "login_20260701"
  }'

200 OK

JSON

{
  "success": true,
  "reward": {
    "user_id": "usr_123456",
    "amount": 5,
    "reason": "daily_login",
    "new_balance": 1255.75,
    "rewarded_at": "2026-07-01T10:20:00Z"
  }
}

Wallet

Deduct STKN

Deducts STKN from a user's wallet for subscription payment contribution. Maximum 30% of subscription value can be covered by STKN — remaining must be paid in fiat.

POST https://api.stocken.io/v1/wallet/deduct

Parameters

Request

Response

Field	Type	Required	Description
user_id	string	required	Stockoo user ID
amount	number	required	STKN amount to deduct (must not exceed 30% of subscription value)
subscription_id	string	required	Subscription plan ID being purchased
subscription_value_inr	number	required	Total subscription cost in INR for validation

cURL

curl -X POST https://api.stocken.io/v1/wallet/deduct \
  -H "X-STKN-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_123456",
    "amount": 150,
    "subscription_id": "pro_monthly",
    "subscription_value_inr": 299
  }'

200 OK

JSON

{
  "success": true,
  "deduction": {
    "user_id": "usr_123456",
    "stkn_deducted": 150,
    "inr_covered": 89.70,
    "remaining_inr": 209.30,
    "new_balance": 1100.75,
    "subscription_id": "pro_monthly",
    "deducted_at": "2026-07-01T10:25:00Z"
  }
}

Token

Get STKN Rate

Returns the current STKN to INR exchange rate. Used at checkout to calculate how much INR value a user's STKN covers toward their subscription.

GET https://api.stocken.io/v1/stk/rate

Parameters

Request

Response

ℹ No parameters required. Rate is updated every 5 minutes from the live BNB Chain market price.

cURL

curl -X GET https://api.stocken.io/v1/stk/rate \
  -H "X-STKN-API-Key: your_api_key"

200 OK

JSON

{
  "success": true,
  "rate": {
    "stkn_to_inr": 0.598,
    "stkn_to_usd": 0.0072,
    "source": "PancakeSwap",
    "updated_at": "2026-07-01T10:25:00Z"
  }
}

Partner Ecosystem

Open Ecosystem

STKN is not exclusive to Stockoo. Any authorized third-party application can integrate Stocken into their platform — enabling their users to earn and spend STKN natively. Stockoo is simply the first app in the ecosystem.

🌐 How it works

Partner apps use the same Stocken API endpoints (/wallet/reward, /wallet/deduct, /wallet/balance) with their own API key. All transactions settle on the same BNB Chain smart contract — fully transparent and on-chain.

Who can integrate

Any authorized app via Partner Agreement

Reward Logic

Defined by partner — not Stocken

Settlement

BNB Chain · On-chain

API Key

Unique per partner

Rate Limits

Configurable per partner

Availability

● Phase 4 · Q1 2027

Partner Ecosystem

Reward Logic

Partner apps have full autonomy over their reward structure. Stocken provides the infrastructure — partners decide the rules.

ℹ Stocken does not govern, approve, or restrict how partner apps define their reward amounts or triggers. Each partner is fully responsible for their own reward policy.

Responsibility	Stocken	Partner App
STKN smart contract	✓ Manages	—
API infrastructure	✓ Provides	—
Reward amounts	—	✓ Decides
Reward triggers	—	✓ Decides
Payment terms	—	✓ Decides
On-chain settlement	✓ Handles	—
User wallet management	✓ Handles	—

Partner rewarding a user — cURL

# Partner app rewards their user with STKN
# Amount and reason are fully decided by the partner
curl -X POST https://api.stocken.io/v1/wallet/reward \
  -H "X-STKN-API-Key: partner_app_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "partner_user_789",
    "amount": 50,
    "reason": "trade_completed",
    "reference_id": "trade_abc123"
  }'

Partner Ecosystem

Getting Access

Partner API access is available from Phase 4 (Q1 2027). To apply for early access or register interest, contact the Stocken team.

📩 Apply for Partner Access

Email contact@stocken.io with your app name, use case, and estimated monthly active users. The Stocken team will review and issue a Partner Agreement and API key.

Step	Action
1	Email contact@stocken.io with your app details
2	Sign the Stocken Partner Agreement
3	Receive your unique API key and sandbox access
4	Integrate and test on BNB Testnet
5	Go live on BNB Mainnet