Sign in

v1

latestOpenAPI 3.1.02026-07-13143194365.4 KB
tipping

Send a tip via URL path (REST-style)

Send a tip using URL path parameters for destination and amount, with optional social graph context via query parameters.

Social Graph Context (Query Parameters)

Add attribution metadata via query params:

  • source_post_url - URL where tip was triggered
  • sender_username - Tipper's username
  • sender_profile_url - Tipper's profile URL
  • sender_platform - Platform enum (x, discord, etc.)
  • recipient_username - Recipient's username
  • campaign - Campaign identifier
  • referrer - Referrer identifier
  • custom_metadata - Free-form string (max 250 chars)

For complex context, consider using the JSON body endpoint (POST /v1/tip) instead.

post/v1/tip/{destination}/{amount}

Path parameters

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)

Note: Uses :path converter to support slashes in Twitter URLs.

Example:@olshansky

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)

Note: Uses :path converter to support slashes in Twitter URLs.

amountstring required

Amount to tip. Supports multiple formats:

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

Amount to tip. Supports multiple formats:

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

Query parameters

networkstring nullable

Target blockchain network.

Examples: base, base-sepolia, solana-devnet.

Defaults to DEFAULT_NETWORK (base) if not specified.

Example:base

Target blockchain network.

Examples: base, base-sepolia, solana-devnet.

Defaults to DEFAULT_NETWORK (base) if not specified.

tokenstring nullable

Token symbol to send.

Examples: USDC, ETH.

Defaults to DEFAULT_TOKEN (USDC) if not specified.

Conflict detection: If the amount path includes a token (e.g., 100USDC) and this query param specifies a different token (e.g., ?token=ETH), the request fails with HTTP 400.

Example:USDC

Token symbol to send.

Examples: USDC, ETH.

Defaults to DEFAULT_TOKEN (USDC) if not specified.

Conflict detection: If the amount path includes a token (e.g., 100USDC) and this query param specifies a different token (e.g., ?token=ETH), the request fails with HTTP 400.

source_post_urlstring nullable

URL of the post/tweet where this tip was triggered.

Example:https://x.com/olshansky/status/1234567890

URL of the post/tweet where this tip was triggered.

sender_usernamestring nullable

Sender's username on the social platform.

Example:olshansky

Sender's username on the social platform.

sender_profile_urlstring nullable

URL to the sender's profile.

Example:https://x.com/olshansky

URL to the sender's profile.

sender_platform'x' | 'twitter' | 'reddit' | 'github' | 'tiktok' | 'discord' | 'telegram' | 'farcaster' | 'lens' | 'substack' | 'youtube' | 'website' | 'instagram' | 'linkedin' | 'medium' | 'soundcloud' | 'twitch' | 'bluesky' | 'facebook' | 'spotify' | 'pinterest' | 'patreon' | 'grove' | 'other' | 'custom'

Social platforms for context attribution in tips.

This enum defines WHERE a tip originated from (the sender's platform context), not where the tip is going. For destination types, see DestinationKind.

Used in TipContext to track:

  • sender_platform: Which platform the tipper used (Twitter bot, Discord bot, etc.)
  • Attribution/analytics for understanding tip sources

Note: "x" is the canonical name for Twitter/X. Both "x" and "twitter" are accepted on input, but "x" is used for storage and output. Use normalize_platform() to convert "twitter" → "x".

Inherits from str so values serialize naturally to JSON.

Social platform where the tip originated.

recipient_usernamestring nullable

Recipient's username on the social platform.

Example:vitalik

Recipient's username on the social platform.

recipient_profile_urlstring nullable

URL to the recipient's profile.

Example:https://x.com/vitalik

URL to the recipient's profile.

campaignstring nullable

Campaign or initiative identifier.

Example:hackathon-2024

Campaign or initiative identifier.

referrerstring nullable

Referrer or source identifier.

Example:grove-twitter-bot

Referrer or source identifier.

custom_metadatastring nullable

Custom metadata string (max 250 characters).

Example:{"note": "great work!"}

Custom metadata string (max 250 characters).

Headers

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

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