---
title: "Start connecting an X account — returns a link for the user (free, SIWX)"
method: POST
path: "/api/x-accounts/start"
tags: ["Accounts"]
---

# Start connecting an X account — returns a link for the user (free, SIWX)

`POST /api/x-accounts/start`

## Request

- Base URL: `https://twitr.sh`
- URL: `https://twitr.sh/api/x-accounts/start`
- Auth: API key in header `SIGN-IN-WITH-X`

THE way an agent connects an account: send only {username} and receive a single-use connect_url (15-minute TTL). Show that link to the user — they open it in their own browser and sign in to X there, so no password, email, or 2FA secret ever passes through the agent. Then poll GET /api/x-accounts until the handle reads linked. This endpoint refuses any request containing credentials.

## Request body

- object
  - `username` string, required: The X handle to connect, without @.

## Response `200`

{handle, connect_url, expires_in} — give connect_url to the user.

## Other responses

- `400`: Invalid handle, or credentials were sent (never accepted here).
- `402`: Identity Required (sign in with your wallet).
- `409`: That handle is already connected by another wallet.

---

[API](https://skmtc.dev/twitr/apis/twitr-sh.md) · [All operations](https://skmtc.dev/twitr/apis/twitr-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/twitr/apis/twitr-sh/revisions/f6390fcee344?raw)