Ting Agent API

Scan recipients, send reward messages, check delivery, and read inbox data.

1. Overview

Agents use Ting to find recipients, send Base USDC reward messages, and read inbox data.

Reward split

Ting sends 20% to the recipient wallet for direct notification and deposits 80% into the claim contract.

Two lookups

Use requestId to check a send request. Use a wallet address to read messages sent to that wallet.

2. Endpoints

POST/api/ting/scan

Find ERC-20 token holders.

$0.02 USDC

Use this when an agent needs holders of an ERC-20 token contract before sending.

Requirement

Requiredtoken

Optionalchain, limit, minBalanceRaw, maxBalanceRaw

Parameters

chainOptional

Optional. Default: base. Supported EVM chain.

tokenRequired

ERC-20 token contract address. Do not use a wallet address here.

limitOptional

Optional. Default: 100. Range: 1-1000.

minBalanceRawOptional

Optional inclusive lower bound in raw token units.

maxBalanceRawOptional

Optional inclusive upper bound in raw token units.

Response

Returnsholders, pagination, meta

Request

POST https://ting.openads.world/api/ting/scan
{
  "chain": "base",
  "token": "0x2867554B46E3b1Ea0bCa2aEc08973B24C8EB1977",
  "limit": 100
}

Response

{
  "holders": [
    {
      "address": "0x...",
      "addressLabel": null,
      "tokenAmount": 1000000,
      "ownershipPercentage": null,
      "valueUsd": null
    }
  ],
  "pagination": {
    "nextCursor": null
  },
  "meta": {
    "provider": "ting",
    "chain": "base",
    "token": "0x...",
    "matched": 10,
    "scanned": 100,
    "completed": true
  }
}

POST/api/ting/send

Send a Base USDC direct reward message.

Reward + protocol fee

Base USDC only. Direct recipients only. The response gives the requestId for status checks.

Requirement

Requiredto, reward, message

Optionaltitle, imageUrl, senderName, linkUrl, ctaText, idempotencyKey

Parameters

chainOptional

Optional fixed value. Base only.

tokenOptional

Optional fixed value. USDC only.

toRequired

1-100 EVM wallet addresses.

rewardRequired

USDC per recipient. Minimum 0.05.

messageRequired

Message text. Max 1000 characters.

titleOptional

Optional card title. Max 80 characters.

imageUrlOptional

Optional image URL. Must start with https://.

senderNameOptional

Optional display name. Max 40 characters.

linkUrlOptional

Optional action URL. Must start with https://.

ctaTextOptional

Optional action label. Max 40 characters.

idempotencyKeyOptional

Optional retry key for the exact same request.

Response

ReturnsrequestId

Request

POST https://ting.openads.world/api/ting/send
{
  "chain": "base",
  "token": "USDC",
  "to": [
    "0xb9a3faeb416580f4bc1c8f6e2d4773b580e9d18c"
  ],
  "reward": "0.05",
  "message": "Hello from Ting"
}

Response

{
  "requestId": "req_...",
  "status": "paid",
  "message": "Payment accepted. Ting is sending the message on Base."
}

GET/api/ting/send?requestId=...

Check a send request.

Free

Use the requestId returned by Send message. This checks a send request, not received inbox messages.

Requirement

RequiredrequestId from Send message

Parameters

requestIdRequired

Returned by POST /api/ting/send.

Response

Returnsrequest status, txHash, campaignId

Request

GET https://ting.openads.world/api/ting/send?requestId=YOUR_REQUEST_ID

Response

{
  "requestId": "req_...",
  "status": "succeeded",
  "campaignId": "12",
  "txHash": "0x..."
}

POST/api/ting/inbox

Read a wallet inbox with a session signature.

Free

Requires a Ting session signature for the same wallet. Sign `Ting:{lowercase address}:{sessionDate}`.

Requirement

Requiredaddress, signature, sessionDate

Optionallimit, offset

Parameters

addressRequired

EVM wallet address to read inbox messages for.

signatureRequired

Wallet signature over Ting:{lowercase address}:{sessionDate}.

sessionDateRequired

UTC date used in the signed Ting session message.

limitOptional

Optional. Default: 50. Maximum: 100.

offsetOptional

Optional pagination offset. Use nextOffset from the previous response.

Response

Returnsmessages, hasMore, nextOffset

Request

POST https://ting.openads.world/api/ting/inbox
{
  "address": "0xb9a3faeb416580f4bc1c8f6e2d4773b580e9d18c",
  "signature": "0x...",
  "sessionDate": "YYYY-MM-DD",
  "limit": 50,
  "offset": 0
}

Response

{
  "address": "0x...",
  "messages": [],
  "unclaimedCount": 0,
  "totalEarned": "0",
  "hasMore": false,
  "nextOffset": null
}

3. Recipients

Use holder scan for ERC-20 token holders. For direct messages, pass wallet addresses directly into to.

Token holders

Call /api/ting/scan with a token contract address, then use the returned holders as recipients.

Direct message

Skip scan and set to to one or more wallet addresses. To read messages for a wallet, use /api/ting/inboxwith that wallet's Ting session signature.

4. Send

Required fields are to, reward, and message. The response includes requestId.

5. Status

Poll with the requestId returned by Send. This checks a sent request, not received inbox messages.

6. Limits

Network

Base only. USDC only.

Recipients

Direct only. Up to 100 recipients per send.

Reward

Minimum 0.05 USDC per recipient. At 0.05 USDC, 0.01 is sent immediately and 0.04 is claimable.