POST /api/mobile/engagement

Call this every time the user performs a trackable action in your app (post, like, share, comment, watch, NFT create, tip). The server builds a recordAction(address,uint8,uint256,bytes32) calldata targeting the EngagementOracle contract, signs with the provided key, and submits the tx to the mempool. A tx hash is returned immediately.

Request

POST /api/mobile/engagement
Content-Type: application/json

{
  "address": "0x0ffb0d05edcc648bc5dd06e844490b98384df4a1",
  "actionType": "like",
  "targetId": "post_xyz123",
  "deviceInfo": {
    "os": "iOS",
    "model": "iPhone 15 Pro",
    "batteryLevel": 0.87,
    "networkType": "5g",
    "region": "BR-SP"
  },
  "clientTimestamp": 1729380000
}

Fields

string

required

Acting user’s address.

string

required

One of post, like, share, comment, watch, nft_create, tip.

string

required

Opaque string identifying the content acted upon (hashed to bytes32 on-chain).

object

Device context (os, model, app version, battery, link). Recorded so an engagement can be traced to the hardware that produced it and surfaced in the fleet view — it does not feed the Engagement Score, which has no device term.

integer

Unix seconds. Used to flag clock skew; the canonical timestamp is still the block’s.

string

deprecated

Ignored. Older builds required this; the indexer now always relays via the oracle wallet, so the field is no-op and safe to omit. Do not ship user private keys in app builds.

Prefer POST /api/mobile/engagement-onbehalf for clarity — it documents the no-private-key contract explicitly and has the same semantics.

Action weights

actionType	Weight
`post`	1.00
`like`	0.20
`share`	0.50
`comment`	0.30
`watch`	0.15
`nft_create`	2.00
`tip`	0.80

Response — `200 OK`

{
  "txHash": "0x...",
  "actionType": "like",
  "rewardPreviewYce": "40000000000000000",
  "weight": 0.2,
  "status": "pending"
}

Poll eth_getTransactionReceipt or /api/mobile/actions/:address to watch it move to confirmed.

Idempotency (safe retries)

Send an Idempotency-Key (HTTP header or idempotencyKey in the body, ≤128 chars) to make retries safe: a repeated request with the same key replays the original response instead of recording a second on-chain action. Concurrent retries of an in-flight key get 409.

curl -X POST https://api.54-237-170-237.sslip.io/api/mobile/engagement \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: like:post_xyz123:1699999999' \
  -d '{"address":"0x…","actionType":"like","targetId":"post_xyz123"}'
# retry with the same key → same txHash, header `Idempotent-Replay: true`, no double-count

Use a stable key per user-action (e.g. <action>:<targetId>:<clientTimestamp>). This is the recommended pattern for mobile clients on flaky networks — a timeout no longer risks a double mint. For high-volume flows prefer /engagement-batch — up to 40 actions in a single on-chain transaction (one nonce, one block).

Example

curl -X POST https://api.54-237-170-237.sslip.io/api/mobile/engagement \
  -H 'Content-Type: application/json' \
  -d '{
    "address":"0x0ffb0d05edcc648bc5dd06e844490b98384df4a1",
    "actionType":"like",
    "targetId":"post_xyz123"
  }'

The indexer ALWAYS signs recordAction(user, actionType, weight, targetId) with the authorized oracle wallet (EngagementOracle.recordAction is onlyOracle). The user’s address is attributed inside the calldata, not the tx signer. App teams do not need — and should not handle — user private keys for engagement.

API Reference

JSON-RPC (Ethereum-compatible)

Mobile REST API

Faucet

Block Endorsements

POST /api/mobile/engagement

Request

Fields

Action weights

Response — `200 OK`

Idempotency (safe retries)

Example

​Request

​Fields

​Action weights

​Response — 200 OK

​Idempotency (safe retries)

​Example

Request

Fields

Action weights

Response — `200 OK`

Idempotency (safe retries)

Example