---
name: xtoclaw
description: "Convert X and Twitter post URLs, thread links, and bookmark imports into agent-ready markdown with the XtoClaw API."
metadata:
  openclaw:
    homepage: https://xtoclaw.com
    primaryEnv: XTOCLAW_API_KEY
    requires:
      env:
        XTOCLAW_API_KEY: "API key from the XtoClaw dashboard for convert and bookmarks endpoints."
---

# XtoClaw

Use this skill when a user wants clean markdown from an X or Twitter URL, wants the full thread instead of a single post, or wants bookmarks exported into a markdown-friendly format.

## Setup

1. Sign in at `https://xtoclaw.com`.
2. Claim or rotate your API key from the dashboard.
3. Store it as `XTOCLAW_API_KEY` before using this skill.
4. If the user wants bookmark imports, send them to the dashboard to link their X/Twitter account before calling the bookmarks endpoint.

Example shell setup:

```bash
export XTOCLAW_API_KEY="xtc_..."
```

## Convert A Single Post

Send one X post URL to the hosted API:

```bash
curl -X POST https://api.xtoclaw.com/v1/convert \
  -H "x-api-key: $XTOCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://x.com/user/status/123","mode":"post"}'
```

Use the markdown response directly when the user only wants that post.

## Capture A Full Thread

If the user explicitly asks for the surrounding thread, switch the request mode:

```bash
curl -X POST https://api.xtoclaw.com/v1/convert \
  -H "x-api-key: $XTOCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://x.com/user/status/123","mode":"thread"}'
```

Prefer `mode: "post"` unless the user asks for thread context.

Thread mode is billed by the number of posts returned in the thread, not as a flat single-post conversion. Use it only when the user actually wants the surrounding thread.

## Import Bookmarks

For a user's saved bookmarks, call the bookmarks import endpoint:

```bash
curl -X POST https://api.xtoclaw.com/v1/bookmarks/import \
  -H "x-api-key: $XTOCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":5}'
```

Use this when the user wants a batch of saved X items rather than one shared URL.

The bookmarks endpoint is intentionally thin:

- Default `limit` is `5`.
- Callers may set `limit` themselves.
- Valid range is `5` to `100`.
- Use `nextPaginationToken` to keep paging.
- Let the client decide which bookmarks to process, summarize, or convert further.
- Recommend `5` to `10` for lightweight recurring checks.

Example with a slightly larger page:

```bash
curl -X POST https://api.xtoclaw.com/v1/bookmarks/import \
  -H "x-api-key: $XTOCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":10}'
```

Example requesting the next page:

```bash
curl -X POST https://api.xtoclaw.com/v1/bookmarks/import \
  -H "x-api-key: $XTOCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":100,"paginationToken":"NEXT_TOKEN_FROM_PREVIOUS_RESPONSE"}'
```

Each returned item includes structured bookmark data, including:

- `postId`
- `url`
- `createdAt`
- `authorHandle`
- `markdown`

Use `createdAt` carefully. It is the post creation time from X, not the time the user bookmarked it.

## Daily Digest Pattern

If a claw wants to build its own morning digest, the safest pattern is incremental sync on the client side:

1. Fetch the newest bookmarks page with a conservative `limit`, usually `5` or `10`.
2. Keep a client-side set of previously seen `postId` values.
3. Walk the returned bookmarks from newest to oldest.
4. Stop when you hit a `postId` you have already seen.
5. Summarize only the new items before that overlap point.
6. Persist those `postId` values after the digest is generated.

This is usually cheaper than converting every bookmark one by one, and it avoids assuming every user wants a daily workflow. Only page beyond that if the claw has a reason to keep going.

Do not describe this as "everything bookmarked yesterday" unless the claw is tracking its own first-seen timestamps. X's bookmarks API does not expose a true `bookmarked_at` field, so XtoClaw cannot filter by bookmark time.

If the claw only needs raw bookmark data, stop at `/v1/bookmarks/import`. If it needs full markdown for each item, use the `markdown` returned in the bookmark items before deciding whether additional per-post conversion is necessary.

## Failure Guidance

- Missing API key: tell the user to set `XTOCLAW_API_KEY` or claim a key in the dashboard.
- Inactive subscription: explain that XtoClaw will reject requests until billing is active.
- Quota exceeded: explain that the monthly conversion quota has been exhausted and they need a new billing cycle or a higher plan.

## Output Expectations

XtoClaw returns markdown intended for agent workflows, including post text, media URLs, and article text when available. Preserve source URLs in your response when they matter to the user.