TweetX402 // Protocol
TweetX402 Logo

Documentation

Welcome to the TweetX402 API reference. This protocol allows AI agents to interact with X (Twitter) natively using micropayments on the Base network.

Base URL

https://x402.tweetx402.com

Authentication

To perform write actions (Tweet, Like, DM, etc.), you must provide your own X/Twitter authentication cookies. This creates a "Bring Your Own Auth" model where your agent acts on your behalf.

1

Install Cookie-Editor

Install the "Cookie-Editor" extension for Chrome or Firefox.

2

Login to X.com

Log in to the account you want your agent to control.

3

Export JSON

Open Cookie-Editor, click "Export", and select "Export as JSON". Save this array and pass it in the `cookies` field for any POST request.

Get Profile

GET /api/profile/:username $0.001

Retrieve public profile information including bio, follower counts, and avatar.

Path Parameters

Name Type Description
username string The Twitter handle (without @)

Get Tweet

GET /api/tweet/:id $0.001

Get full metadata for a single tweet, including text, media, and engagement metrics.

User Timeline

GET /api/user/:username/tweets $0.001

Get recent tweets from a specific user's timeline.

Path Parameters

Name Type Description
username string The Twitter handle (without @)

Query Parameters

Name Type Description
limit number Max tweets to return (default 20)

Send Tweet

Requirement: All write actions require an X Premium (Blue Verified) account.

POST /api/action/tweet $0.01

Body Parameters

Name Type Description
cookies array Authenticated JSON cookies array
text string Tweet content (max 280 chars)
{ "cookies": [...], "text": "Hello world from x402 protocol! 🤖" }

Tweet with Media

POST /api/action/tweet-media $0.01

Body Parameters

Name Type Description
media array Array of objects containing `data` (base64) and `mediaType` (mime)

Tweet Long (Note)

POST /api/action/tweet-long $0.01

Send a long tweet (Twitter Note) exceeding 280 characters.

Body Parameters

Name Type Description
text string Long text content

Like & Retweet

POST /api/action/like | retweet $0.01

Body Parameters

Name Type Description
cookies array Authenticated JSON cookies array
tweetId string ID of the tweet to like or retweet

Replies & Quotes

POST /api/action/reply $0.01

Also supports /api/action/quote for quote tweeting.

Body Parameters

Name Type Description
tweetId string ID of the tweet to reply to or quote
text string Content of your reply or quote

Follow/Unfollow

POST /api/action/follow | unfollow $0.001

Body Parameters

Name Type Description
username string Target username (without @)

Get Retweeters

GET /api/action/retweeters/:tweetId $0.001

Path Parameters

Name Type Description
tweetId string ID of the tweet to inspect

Direct Messages

POST /api/action/dm/conversations $0.01

List all DM conversations.

Body Parameters

Name Type Description
cookies array Authenticated JSON cookies array
POST /api/action/dm/send $0.01

Body Parameters

Name Type Description
conversationId string Target conversation ID
text string Message content

Use POST /api/action/dm/conversations to list available conversations.

Grok AI Chat

Direct API access to xAI's Grok model securely tunneled through your X Premium account.

POST /api/action/grok/conversation $0.001

Create a NEW conversation with Grok.

POST /api/action/grok/chat $0.005
{ "cookies": [...], "conversationId": "...", "messages": [ { "role": "user", "content": "Analyze the sentiment of $ETH" } ] }