Send a tip via JSON body (recommended for bots/integrations)

Send a tip using a JSON request body. Recommended for programmatic access, bots, and integrations that need to track social graph context.

Social Graph Context

The optional context field allows you to attach attribution metadata to tips:

Field	Description	Example
source_post_url	URL where the tip was triggered	https://x.com/user/status/123
sender_username	Tipper's username	olshansky
sender_profile_url	Tipper's profile URL	https://x.com/olshansky
sender_platform	Platform enum	x, discord, telegram, etc.
recipient_username	Recipient's username	vitalik
campaign	Campaign/bot identifier	grove-twitter-bot-v1
referrer	Referrer identifier	twitter-bot
custom_metadata	Free-form string (max 250 chars)	{"note": "great work!"}

Supported Platforms

x, reddit, github, tiktok, substack, youtube, discord, telegram, farcaster, lens, other

Metadata Storage

Context is stored in the tip's metadata_json under a nested context key with ctx_ prefixed fields, preserving separation from auto-resolved metadata (like x_username from destination resolution).

authorizationstring nullable

Bearer JWT that identifies the sending account.

Required for all tipping calls
Format: Bearer <jwt_token>
Obtain JWT from /v1/fund after funding your account

Bearer JWT that identifies the sending account.

Required for all tipping calls
Format: Bearer <jwt_token>
Obtain JWT from /v1/fund after funding your account

Request body

destinationstring required

Who to tip. Accepts multiple formats:

Grove handle: @olshansky or olshansky (resolves via Grove account)
EVM address: 0x9ab39B84aC4DE6D705C5f051c07db8fE72890953
Solana address: 9kucRUCUiYwJLDBBi5GXb4KeqgiRZ6uJeMdLwAuV6pUC
ENS name: vitalik.eth (resolved via Ethereum mainnet)
Domain: olshansky.info (looks up address from llms.txt)
Twitter/X: x.com/olshansky (looks up address from bio)

amountstring required

Amount to tip. Supports multiple formats:

Plain number: 0.01 (uses token from query or DEFAULT_TOKEN)
With currency: 100USDC, 0.5ETH
Dollar prefix: $1 (interpreted as 1 USDC)

networkstring nullable

Target blockchain network. Examples: base, base-sepolia, solana-devnet. Defaults to DEFAULT_NETWORK (base) if not specified.

tokenstring nullable

Token symbol to tip. Examples: USDC, ETH. Defaults to DEFAULT_TOKEN (USDC) if not specified. Note: If amount includes a token (e.g., 100USDC) and this field specifies a different token, the request fails with 400.

Example request

{
  "description": "Tip 1 USDC to a domain with llms.txt",
  "summary": "Simple tip to a domain",
  "value": {
    "amount": "1",
    "destination": "olshansky.info"
  }
}

Response

Successful Response

tip_idstring required

statusstring required

destinationstring required

from_addressstring required

receiver_addressstring required

amount_sentstring required

amount_receivedstring required

fee_amountstring required

tx_hashstring required

new_balancestring required

networkstring required

v1