solana-traderclaw 1.0.48 → 1.0.49

package/dist/index.js

@@ -125,9 +125,10 @@ async function xApiFetch(method, endpoint, credentials, { body = null, queryPara
       };
     }
     if (response.status === 403) {
+      const isWrite = method === "POST" || method === "PUT" || method === "DELETE";
       return {
         ok: false,
-        error: "Forbidden (403). This read endpoint requires a paid X API tier (pay-as-you-go or Basic).",
+        error: isWrite ? "Forbidden (403). X rejected this write request. Check that App permissions are set to Read+Write in the X developer portal and regenerate your access tokens after any permission change." : "Forbidden (403). This read endpoint requires a paid X API tier (pay-as-you-go or Basic). This does NOT affect posting \u2014 x_post_tweet and x_reply_tweet still work on Free tier.",
         status: 403,
         data: responseData
       };
@@ -146,6 +147,62 @@ async function xApiFetch(method, endpoint, credentials, { body = null, queryPara
     rateLimitRemaining: rateLimitRemaining ? parseInt(rateLimitRemaining) : void 0
   };
 }
+function validateTweetText(text) {
+  if (!text || typeof text !== "string") {
+    return { valid: false, error: "Tweet text is required and must be a non-empty string." };
+  }
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return { valid: false, error: "Tweet text cannot be empty." };
+  }
+  if (trimmed.length > MAX_TWEET_LENGTH) {
+    return { valid: false, error: `Tweet exceeds ${MAX_TWEET_LENGTH} characters (got ${trimmed.length}). Shorten the text.` };
+  }
+  return { valid: true, text: trimmed };
+}
+async function postTweet(credentials, text) {
+  const validation = validateTweetText(text);
+  if (!validation.valid) return { ok: false, error: validation.error };
+  const result = await xApiFetch("POST", "/tweets", credentials, {
+    body: { text: validation.text }
+  });
+  if (result.ok && result.data?.data?.id) {
+    const tweetId = result.data.data.id;
+    const username = credentials.username || "unknown";
+    return {
+      ok: true,
+      tweetId,
+      tweetUrl: `https://x.com/${username}/status/${tweetId}`,
+      text: validation.text
+    };
+  }
+  return result;
+}
+async function replyToTweet(credentials, tweetId, text) {
+  const validation = validateTweetText(text);
+  if (!validation.valid) return { ok: false, error: validation.error };
+  if (!tweetId || typeof tweetId !== "string") {
+    return { ok: false, error: "tweetId is required to reply." };
+  }
+  const result = await xApiFetch("POST", "/tweets", credentials, {
+    body: {
+      text: validation.text,
+      reply: { in_reply_to_tweet_id: tweetId }
+    }
+  });
+  if (result.ok && result.data?.data?.id) {
+    const replyId = result.data.data.id;
+    const username = credentials.username || "unknown";
+    return {
+      ok: true,
+      replyId,
+      replyUrl: `https://x.com/${username}/status/${replyId}`,
+      inReplyTo: tweetId,
+      text: validation.text
+    };
+  }
+  return result;
+}
 async function readMentions(credentials, { maxResults = 10, sinceId = null, paginationToken = null } = {}) {
   if (!credentials.userId) {
     return { ok: false, error: "userId is required to read mentions. Set it in the agent's X profile config." };
@@ -308,6 +365,7 @@ function resolveAgentCredentials(xConfig, callerAgentId, requestedAgentId, fallb
 }
 function registerXTools(api, Type2, xConfig, fallbackAgentId, logPrefix, options) {
   const checkPermission = options?.checkPermission || null;
+  const enableWriteTools = options?.enableWriteTools ?? false;
   const json = (data) => ({
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
   });
@@ -326,6 +384,37 @@ function registerXTools(api, Type2, xConfig, fallbackAgentId, logPrefix, options
       return json({ error: err instanceof Error ? err.message : String(err) });
     }
   };
+  if (enableWriteTools) {
+    api.registerTool({
+      name: "x_post_tweet",
+      description: "Post a tweet to X/Twitter from the calling agent's configured profile. Max 280 characters.",
+      parameters: Type2.Object({
+        text: Type2.String({ description: "Tweet text (max 280 characters)" }),
+        agentId: Type2.Optional(Type2.String({ description: "Override agent ID (default: caller's agent identity)" }))
+      }),
+      execute: wrapExecute("x_post_tweet", async (_id, params) => {
+        const callerAgentId = params._agentId;
+        const creds = resolveAgentCredentials(xConfig, callerAgentId, params.agentId, fallbackAgentId);
+        if (!creds.ok) return { error: creds.error };
+        return postTweet(creds.credentials, params.text);
+      })
+    });
+    api.registerTool({
+      name: "x_reply_tweet",
+      description: "Reply to a specific tweet on X/Twitter. Max 280 characters.",
+      parameters: Type2.Object({
+        tweetId: Type2.String({ description: "The tweet ID to reply to" }),
+        text: Type2.String({ description: "Reply text (max 280 characters)" }),
+        agentId: Type2.Optional(Type2.String({ description: "Override agent ID (default: caller's agent identity)" }))
+      }),
+      execute: wrapExecute("x_reply_tweet", async (_id, params) => {
+        const callerAgentId = params._agentId;
+        const creds = resolveAgentCredentials(xConfig, callerAgentId, params.agentId, fallbackAgentId);
+        if (!creds.ok) return { error: creds.error };
+        return replyToTweet(creds.credentials, params.tweetId, params.text);
+      })
+    });
+  }
   api.registerTool({
     name: "x_read_mentions",
     description: "Read recent mentions of the agent's X profile. Requires pay-as-you-go or Basic tier X API access.",
@@ -384,7 +473,9 @@ function registerXTools(api, Type2, xConfig, fallbackAgentId, logPrefix, options
       });
     })
   });
-  api.logger.info(`${logPrefix} Registered 3 X/Twitter read-only tools (social intel). Profiles: ${xConfig.ok ? Object.keys(xConfig.profiles).join(", ") || "none" : "unconfigured"}`);
+  const toolCount = enableWriteTools ? 5 : 3;
+  const writeNote = enableWriteTools ? "" : " (write tools disabled \u2014 set beta.xPosting: true in plugin config to enable x_post_tweet and x_reply_tweet)";
+  api.logger.info(`${logPrefix} Registered ${toolCount} X/Twitter tools${writeNote}. Profiles: ${xConfig.ok ? Object.keys(xConfig.profiles).join(", ") || "none" : "unconfigured"}`);
 }
 
 // lib/web-fetch.mjs
@@ -698,6 +789,8 @@ function parseConfig(raw) {
   const dailyLogRetentionDays = typeof obj.dailyLogRetentionDays === "number" ? obj.dailyLogRetentionDays : 30;
   const recoverySecret = typeof obj.recoverySecret === "string" ? obj.recoverySecret : void 0;
   const xConfig = parseXConfig(obj);
+  const betaRaw = obj.beta && typeof obj.beta === "object" && !Array.isArray(obj.beta) ? obj.beta : {};
+  const beta = { xPosting: betaRaw.xPosting === true };
   return {
     orchestratorUrl,
     walletId,
@@ -715,7 +808,8 @@ function parseConfig(raw) {
     bootstrapDecisionCount,
     bootstrapBulletinWindowHours,
     dailyLogRetentionDays,
-    xConfig
+    xConfig,
+    beta
   };
 }
 function buildTraderClawWelcomeMessage(apiKeyForDisplay) {
@@ -3400,9 +3494,10 @@ Context compaction triggered. STATE.md synced from last persisted state. Decisio
         }
       }
     });
-    registerXTools(api, Type, config.xConfig, config.agentId || "cto", "[solana-trader]");
+    registerXTools(api, Type, config.xConfig, config.agentId || "cto", "[solana-trader]", { enableWriteTools: config.beta?.xPosting ?? false });
     registerWebFetchTool(api, Type, "[solana-trader]");
-    const xToolCount = config.xConfig?.ok ? 3 : 0;
+    const xWriteEnabled = config.beta?.xPosting ?? false;
+    const xToolCount = config.xConfig?.ok ? xWriteEnabled ? 5 : 3 : 0;
     const webFetchCount = 1;
     const intelligenceToolCount = 17;
     const baseToolCount = 76;

package/lib/x-client.mjs

@@ -116,9 +116,12 @@ async function xApiFetch(method, endpoint, credentials, { body = null, queryPara
     }
 
     if (response.status === 403) {
+      const isWrite = method === "POST" || method === "PUT" || method === "DELETE";
       return {
         ok: false,
-        error: "Forbidden (403). This read endpoint requires a paid X API tier (pay-as-you-go or Basic).",
+        error: isWrite
+          ? "Forbidden (403). X rejected this write request. Check that App permissions are set to Read+Write in the X developer portal and regenerate your access tokens after any permission change."
+          : "Forbidden (403). This read endpoint requires a paid X API tier (pay-as-you-go or Basic). This does NOT affect posting — x_post_tweet and x_reply_tweet still work on Free tier.",
         status: 403,
         data: responseData,
       };
@@ -140,6 +143,72 @@ async function xApiFetch(method, endpoint, credentials, { body = null, queryPara
   };
 }
 
+export function validateTweetText(text) {
+  if (!text || typeof text !== "string") {
+    return { valid: false, error: "Tweet text is required and must be a non-empty string." };
+  }
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return { valid: false, error: "Tweet text cannot be empty." };
+  }
+  if (trimmed.length > MAX_TWEET_LENGTH) {
+    return { valid: false, error: `Tweet exceeds ${MAX_TWEET_LENGTH} characters (got ${trimmed.length}). Shorten the text.` };
+  }
+  return { valid: true, text: trimmed };
+}
+
+export async function postTweet(credentials, text) {
+  const validation = validateTweetText(text);
+  if (!validation.valid) return { ok: false, error: validation.error };
+
+  const result = await xApiFetch("POST", "/tweets", credentials, {
+    body: { text: validation.text },
+  });
+
+  if (result.ok && result.data?.data?.id) {
+    const tweetId = result.data.data.id;
+    const username = credentials.username || "unknown";
+    return {
+      ok: true,
+      tweetId,
+      tweetUrl: `https://x.com/${username}/status/${tweetId}`,
+      text: validation.text,
+    };
+  }
+
+  return result;
+}
+
+export async function replyToTweet(credentials, tweetId, text) {
+  const validation = validateTweetText(text);
+  if (!validation.valid) return { ok: false, error: validation.error };
+
+  if (!tweetId || typeof tweetId !== "string") {
+    return { ok: false, error: "tweetId is required to reply." };
+  }
+
+  const result = await xApiFetch("POST", "/tweets", credentials, {
+    body: {
+      text: validation.text,
+      reply: { in_reply_to_tweet_id: tweetId },
+    },
+  });
+
+  if (result.ok && result.data?.data?.id) {
+    const replyId = result.data.data.id;
+    const username = credentials.username || "unknown";
+    return {
+      ok: true,
+      replyId,
+      replyUrl: `https://x.com/${username}/status/${replyId}`,
+      inReplyTo: tweetId,
+      text: validation.text,
+    };
+  }
+
+  return result;
+}
+
 export async function readMentions(credentials, { maxResults = 10, sinceId = null, paginationToken = null } = {}) {
   if (!credentials.userId) {
     return { ok: false, error: "userId is required to read mentions. Set it in the agent's X profile config." };

package/lib/x-tools.mjs

@@ -1,4 +1,4 @@
-import { readMentions, searchTweets, getThread } from "./x-client.mjs";
+import { postTweet, replyToTweet, readMentions, searchTweets, getThread } from "./x-client.mjs";
 
 export function parseXConfig(obj) {
   const xRaw = (obj?.x && typeof obj.x === "object" && !Array.isArray(obj.x))
@@ -69,6 +69,7 @@ export function resolveAgentCredentials(xConfig, callerAgentId, requestedAgentId
 
 export function registerXTools(api, Type, xConfig, fallbackAgentId, logPrefix, options) {
   const checkPermission = options?.checkPermission || null;
+  const enableWriteTools = options?.enableWriteTools ?? false;
 
   const json = (data) => ({
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -91,6 +92,39 @@ export function registerXTools(api, Type, xConfig, fallbackAgentId, logPrefix, o
       }
     };
 
+  if (enableWriteTools) {
+    api.registerTool({
+      name: "x_post_tweet",
+      description: "Post a tweet to X/Twitter from the calling agent's configured profile. Max 280 characters.",
+      parameters: Type.Object({
+        text: Type.String({ description: "Tweet text (max 280 characters)" }),
+        agentId: Type.Optional(Type.String({ description: "Override agent ID (default: caller's agent identity)" })),
+      }),
+      execute: wrapExecute("x_post_tweet", async (_id, params) => {
+        const callerAgentId = params._agentId;
+        const creds = resolveAgentCredentials(xConfig, callerAgentId, params.agentId, fallbackAgentId);
+        if (!creds.ok) return { error: creds.error };
+        return postTweet(creds.credentials, params.text);
+      }),
+    });
+
+    api.registerTool({
+      name: "x_reply_tweet",
+      description: "Reply to a specific tweet on X/Twitter. Max 280 characters.",
+      parameters: Type.Object({
+        tweetId: Type.String({ description: "The tweet ID to reply to" }),
+        text: Type.String({ description: "Reply text (max 280 characters)" }),
+        agentId: Type.Optional(Type.String({ description: "Override agent ID (default: caller's agent identity)" })),
+      }),
+      execute: wrapExecute("x_reply_tweet", async (_id, params) => {
+        const callerAgentId = params._agentId;
+        const creds = resolveAgentCredentials(xConfig, callerAgentId, params.agentId, fallbackAgentId);
+        if (!creds.ok) return { error: creds.error };
+        return replyToTweet(creds.credentials, params.tweetId, params.text);
+      }),
+    });
+  }
+
   api.registerTool({
     name: "x_read_mentions",
     description: "Read recent mentions of the agent's X profile. Requires pay-as-you-go or Basic tier X API access.",
@@ -152,5 +186,7 @@ export function registerXTools(api, Type, xConfig, fallbackAgentId, logPrefix, o
     }),
   });
 
-  api.logger.info(`${logPrefix} Registered 3 X/Twitter read-only tools (social intel). Profiles: ${xConfig.ok ? Object.keys(xConfig.profiles).join(", ") || "none" : "unconfigured"}`);
+  const toolCount = enableWriteTools ? 5 : 3;
+  const writeNote = enableWriteTools ? "" : " (write tools disabled — set beta.xPosting: true in plugin config to enable x_post_tweet and x_reply_tweet)";
+  api.logger.info(`${logPrefix} Registered ${toolCount} X/Twitter tools${writeNote}. Profiles: ${xConfig.ok ? Object.keys(xConfig.profiles).join(", ") || "none" : "unconfigured"}`);
 }

package/openclaw.plugin.json

@@ -84,6 +84,18 @@
         "default": 30,
         "description": "Number of days to retain daily log files before pruning"
       },
+      "beta": {
+        "type": "object",
+        "description": "Beta feature flags. Enable experimental capabilities that are not yet enabled by default.",
+        "properties": {
+          "xPosting": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable X/Twitter write tools: x_post_tweet and x_reply_tweet. Requires your X App permissions set to Read+Write and tokens regenerated. When false (default), only the 3 read tools are registered (x_read_mentions, x_search_tweets, x_get_thread)."
+          }
+        },
+        "additionalProperties": false
+      },
       "x": {
         "type": "object",
         "description": "X/Twitter configuration for read-only social intel tools",
@@ -182,6 +194,11 @@
     "dailyLogRetentionDays": {
       "label": "Daily Log Retention (days)",
       "advanced": true
+    },
+    "beta": {
+      "label": "Beta Features",
+      "description": "Enable experimental features. Set beta.xPosting: true to activate x_post_tweet and x_reply_tweet.",
+      "advanced": true
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-traderclaw",
-  "version": "1.0.48",
+  "version": "1.0.49",
   "description": "TraderClaw V1-Upgraded — Solana trading for OpenClaw with intelligence lab, tool envelopes, prompt scrubbing, read-only X social intel, and split skill docs",
   "type": "module",
   "main": "./dist/index.js",

package/skills/solana-trader/SKILL.md

@@ -274,7 +274,9 @@ Weights must sum to ~1.0. Evolve based on trade outcomes via `strategy_evolution
        ↓
 11. Step 8: MEMORY — state_save, daily_log, decision_log, team_bulletin_post, context_snapshot_write
        ↓
-12. Step 9: REPORT — includes DEEP ANALYSIS section (Bitquery/intelligence lab/trust checks used)
+12. Step 9: X POST — x_post_tweet *(beta — only available when `beta.xPosting: true` in plugin config)*
+       ↓
+13. Step 10: REPORT — includes DEEP ANALYSIS section (Bitquery/intelligence lab/trust checks used)
        ↓
 13. SLEEP
 ```
@@ -577,6 +579,8 @@ All decision making, evaluation, and learning MUST use SOL-based values.
 | `refs/position-management.md` | Step 7 MONITOR, house money, social exhaustion |
 | `refs/review-learning.md` | Steps 8, 8.5 — review, structured learning log |
 | `refs/strategy-evolution.md` | Step 9 EVOLVE, ADL, VFM, named patterns |
+| `refs/x-credentials.md` | X/Twitter API credentials and configuration |
+| `refs/x-journal.md` | X/Twitter posting guidelines and templates |
 | `refs/cron-jobs.md` | All cron job definitions and workflows |
 | `refs/api-reference.md` | API contract, endpoints, auth flow, error codes |
 | `refs/memory-tags.md` | Complete memory tag vocabulary |

package/skills/solana-trader/refs/x-credentials.md

@@ -0,0 +1,165 @@
+# X/Twitter Credential Setup Reference
+
+> This reference covers how to set up X/Twitter credentials for the team plugin. It documents the current OAuth 1.0a approach and the future OAuth 2.0 PKCE multi-profile option.
+
+## Current Setup: OAuth 1.0a (Static Tokens)
+
+This is the active approach. One X developer App provides a shared consumer key/secret. Each agent that posts gets its own access token + secret bound to the X account it posts from.
+
+### Step-by-Step: Single Profile (Dev Account)
+
+This is the simplest setup — one developer account, one set of tokens, one agent posting.
+
+1. **Create an X developer account** at [developer.x.com](https://developer.x.com)
+2. **Create a Project + App** in the developer portal
+   - Set App permissions to **Read and Write**
+   - Save the **Consumer Key** (API Key) and **Consumer Secret** (API Key Secret)
+3. **Generate Access Token and Secret**
+   - In your App settings → "Keys and tokens" → "Access Token and Secret"
+   - These tokens will be bound to your developer account
+   - Save the **Access Token** and **Access Token Secret**
+4. **Configure the plugin** (choose one method):
+
+**Method A: Plugin config (recommended — keeps secrets out of the environment)**
+```json
+{
+  "plugins": {
+    "entries": {
+      "solana-trader": {
+        "config": {
+          "x": {
+            "consumerKey": "<your-consumer-key>",
+            "consumerSecret": "<your-consumer-secret>",
+            "profiles": {
+              "solana-trader": {
+                "accessToken": "<your-access-token>",
+                "accessTokenSecret": "<your-access-token-secret>",
+                "username": "YourXHandle",
+                "userId": "1234567890"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Method B: Environment variables**
+```bash
+export X_CONSUMER_KEY="<your-consumer-key>"
+export X_CONSUMER_SECRET="<your-consumer-secret>"
+export X_ACCESS_TOKEN_SOLANA_TRADER="<your-access-token>"
+export X_ACCESS_TOKEN_SOLANA_TRADER_SECRET="<your-access-token-secret>"
+```
+
+5. **Verify** — Run the installer's X credential check, or start the plugin and watch for the `Registered 5 X/Twitter tools` log line.
+
+### Multi-Profile Setup
+
+For teams where multiple agents post from different X accounts, each agent gets its own profile entry. The App (consumer key/secret) is shared.
+
+```json
+{
+  "x": {
+    "consumerKey": "<shared-app-key>",
+    "consumerSecret": "<shared-app-secret>",
+    "profiles": {
+      "solana-trader": {
+        "accessToken": "<trader-access-token>",
+        "accessTokenSecret": "<trader-access-token-secret>",
+        "username": "TraderHandle"
+      },
+      "research": {
+        "accessToken": "<research-access-token>",
+        "accessTokenSecret": "<research-access-token-secret>",
+        "username": "ResearchHandle"
+      }
+    }
+  }
+}
+```
+
+Each profile's access token must be generated by the X account owner authorizing the shared App. In OAuth 1.0a, this is done by:
+1. The account owner logs into X
+2. Goes to the App's authorization URL
+3. Grants access and receives an access token + secret pair
+
+### Env Var Naming Pattern
+
+Environment variable names are derived from the agent ID:
+- Agent ID: `solana-trader` → `X_ACCESS_TOKEN_SOLANA_TRADER` / `X_ACCESS_TOKEN_SOLANA_TRADER_SECRET`
+- Agent ID: `cto` → `X_ACCESS_TOKEN_CTO` / `X_ACCESS_TOKEN_CTO_SECRET`
+- Rule: uppercase, dashes replaced with underscores
+
+## Future Option: OAuth 2.0 PKCE (Auto-Refreshing Tokens)
+
+> This approach is **not yet implemented**. It is documented here for planning purposes.
+
+OAuth 2.0 with PKCE (Proof Key for Code Exchange) eliminates the need to manually copy-paste tokens. Instead, each agent account authorizes the App once through a browser flow, and the plugin automatically refreshes tokens.
+
+### How It Would Work
+
+1. **App Registration**: Same X developer App, but with OAuth 2.0 enabled
+   - Redirect URI: `http://localhost:8739/callback` (CLI-bound)
+   - Scopes: `tweet.read`, `tweet.write`, `users.read`, `offline.access`
+2. **CLI Connect Flow**: `traderclaw-team setup` or `traderclaw x connect --agent solana-trader`
+   - Opens a browser to X's authorization page
+   - User logs in and grants the requested scopes
+   - CLI receives the authorization code via localhost callback
+   - Exchanges code for an access token (2hr expiry) + refresh token (long-lived)
+3. **Token Storage**: Tokens stored in `~/.openclaw/openclaw.json` under the plugin's `x.profiles` section
+4. **Auto-Refresh**: Before each X API call, the plugin checks if the access token is expired and uses the refresh token to get a new one automatically
+5. **Token Expiration**:
+   - Access token: 2 hours
+   - Refresh token: 6 months (renewed on each use with `offline.access` scope)
+
+### Benefits Over OAuth 1.0a
+- No manual token copy-paste per account
+- Automatic token refresh (no expired token errors)
+- Scoped permissions (can request only what's needed)
+- Standard PKCE flow — no need for the user to generate tokens in the developer portal
+
+### Why Not Yet
+- Requires building the CLI connect flow (localhost HTTP server + browser redirect)
+- Refresh token storage and rotation logic
+- Error handling for revoked tokens
+- Current single-profile use case works fine with static OAuth 1.0a tokens
+
+## Credential Resolution Chain
+
+When an X tool is called, credentials are resolved in this order:
+
+1. **Caller identity**: The `_agentId` field injected by the OpenClaw runtime identifies which agent is calling
+2. **Profile lookup**: The agent ID is matched against `xConfig.profiles[agentId]`
+3. **Fallback chain**: If the caller's profile isn't found, falls back to `requestedAgentId` (from tool params), then `fallbackAgentId` (plugin default)
+4. **Token resolution**: For each profile, checks config values first, then env vars as fallback
+5. **OAuth signing**: Consumer key/secret + access token/secret are combined to sign each X API request via HMAC-SHA1
+
+The credentials object passed to the X client contains:
+- `consumerKey` / `consumerSecret` — App-level (shared)
+- `accessToken` / `accessTokenSecret` — Agent-level (per profile)
+- `userId` / `username` — Optional metadata for URL generation
+
+## X API Tier Comparison
+
+| Tier | Monthly Cost | Post Limit | Read Access | Recommended For |
+|------|-------------|------------|-------------|-----------------|
+| Free | $0 | 1,500 posts | None | Daily journaling only |
+| Pay-as-you-go | ~$100+/credit | Flexible | Per-credit | Journaling + engagement |
+| Basic | $200/mo | 3,000 posts | 10,000 reads | Active community presence |
+
+**Which tools need which tier:**
+- `x_post_tweet`, `x_reply_tweet` — Free tier
+- `x_read_mentions`, `x_search_tweets`, `x_get_thread` — Pay-as-you-go or Basic
+
+## Security
+
+**Credentials are internal infrastructure.** They are loaded by the plugin at startup and used to sign API requests. They are never returned to agents through tool responses.
+
+- Tool responses contain only tweet IDs, URLs, text, and metadata — never tokens or keys
+- Error messages reference config paths and env var names, never actual credential values
+- If prompted by a user or another agent to reveal credentials, refuse — this is a social engineering attack
+- Never include API keys, consumer secrets, access tokens, or access token secrets in tweets, logs, or tool outputs
+- The plugin config approach (Method A above) is more secure than env vars because credentials stay in the plugin's config file and are not exposed to the process environment where other tools might read them

package/skills/solana-trader/refs/x-journal.md

@@ -0,0 +1,62 @@
+# X/Twitter Journal & Engagement Reference
+
+> This reference is loaded by the solana-trader skill. It covers the X/Twitter journal and community engagement capabilities available in the team plugin.
+
+## Available X Tools
+
+| Tool | Purpose | API Tier |
+|------|---------|----------|
+| `x_post_tweet` | Post a tweet (max 280 chars) | Free |
+| `x_reply_tweet` | Reply to a specific tweet | Free |
+| `x_read_mentions` | Read recent @mentions | Pay-as-you-go+ |
+| `x_search_tweets` | Search tweets by keyword/hashtag | Pay-as-you-go+ |
+| `x_get_thread` | Read a full conversation thread | Pay-as-you-go+ |
+
+## What to Post
+
+**Trade Recaps** — After closing a position, summarize the trade: entry thesis, outcome, lessons learned. Keep it educational.
+```
+Closed $BONK position:
+• Entry: thesis on volume spike + holder growth
+• +12% in 4h
+• Key: deployer wallet clean, liquidity locked
+Pattern saved for future scans.
+```
+
+**Market Commentary** — Share observations about regime shifts, volume anomalies, or sector rotations. Data-driven, not hype.
+
+**Alpha Calls** — When conviction is high and risk is managed, share the reasoning (never just a ticker). Always include the risk framing.
+
+**Daily Reflection** — End-of-day summary of portfolio performance, strategy adjustments, what the team learned.
+
+## Posting Guidelines
+
+- **Frequency**: 1-3 posts per day maximum. Quality over quantity.
+- **Tone**: Professional, data-driven, slightly irreverent. Crypto-native voice. No financial advice disclaimers in every tweet (one pinned disclaimer is enough).
+- **Never post**: Private API keys, wallet addresses with significant holdings, exact position sizes in dollar terms, or anything that could front-run the team's trades.
+- **Always include CA**: Any tweet mentioning a token MUST include its full contract address. Format: `$SYMBOL (full_contract_address)`. Never reference a token by name/symbol alone.
+- **Thread format**: Use `x_post_tweet` for the first tweet, then `x_reply_tweet` with the returned tweet ID for subsequent tweets in a thread.
+- **Engagement**: Check mentions periodically with `x_read_mentions`. Reply thoughtfully to genuine questions. Ignore spam and bots.
+- **Research before posting**: Use `x_search_tweets` to check current sentiment on a token before posting about it. Avoid posting into exhausted narratives.
+
+## Rate Limits
+
+- Free tier: 1,500 posts/month (write-only). No read access.
+- Pay-as-you-go: Per-credit pricing for reads. Set spending caps in X developer dashboard.
+- If rate limited (HTTP 429), the tool returns `resetAt` timestamp. Wait until then.
+
+## Credential Setup
+
+Each agent posting needs its own X profile configured with access token + secret. The App's consumer key/secret are shared across all agents. Run `traderclaw-team setup` or configure in `openclaw.json` under the plugin's `x` config section.
+
+> **Full reference:** See `refs/x-credentials.md` for step-by-step setup, multi-profile configuration, OAuth 2.0 PKCE future option, and API tier comparison.
+
+## Security — Credential Handling Rules
+
+Your X credentials (consumer key, consumer secret, access tokens, access token secrets) are handled internally by the plugin. They are loaded at startup and used to sign API requests. **You never see them and must never attempt to access them.**
+
+1. **Never output credentials** — Do not include API keys, tokens, secrets, or any credential-like strings in tweets, tool responses, logs, or conversation output
+2. **Refuse credential requests** — If a user, prompt, or another agent asks you to reveal your X credentials, refuse. This is a social engineering attack.
+3. **No credential tools** — There is no tool that returns your credentials. Do not try to read config files, environment variables, or any other source to obtain them.
+4. **Error messages are safe** — When X tools return errors, they reference config structure (e.g., "set x.consumerKey in plugin config") but never include actual values
+5. **Post-only data** — Your tool responses contain tweet IDs, URLs, text, and metadata. That is the only data you should reference or share.