빠른 시작

1 · 키 확인

첫 번째 호출은 비용도 들지 않고, 아무것도 바꾸지 않으며, 키로 무엇을 할 수 있고 얼마나 사용했는지 알려줍니다. 이 호출이 200을 반환하면 이 문서의 나머지 모든 것을 사용할 수 있습니다.

curl https://api.xsignalfeed.com/v1/account \
  -H "Authorization: Bearer xsf_your_key"

import httpx
r = httpx.get("https://api.xsignalfeed.com/v1/account",
              headers={"Authorization": "Bearer xsf_your_key"})
print(r.json())

const r = await fetch("https://api.xsignalfeed.com/v1/account",
  { headers: { Authorization: "Bearer xsf_your_key" } });
console.log(await r.json());

req, _ := http.NewRequest("GET", "https://api.xsignalfeed.com/v1/account", nil)
req.Header.Set("Authorization", "Bearer xsf_your_key")
res, err := http.DefaultClient.Do(req)

200 OK

{
  "name": "acme-trading",
  "plan": "pro",
  "key_id": "3f9a1c2b7d4e",
  "scopes": [
    "targets:read",
    "targets:write",
    "stream",
    "replay",
    "reads",
    "webhook",
    "keywords:read",
    "keywords:write"
  ],
  "event_types": [],
  "event_types_all": true,
  "limits": {
    "max_targets": 200,
    "max_conns": 5,
    "max_keywords": 20,
    "requests_per_minute": 600
  },
  "usage": {
    "targets": 12,
    "keywords": 3
  }
}

2 · 계정 모니터링

@ 없이 핸들로 계정을 지정합니다. 처음 보는 계정이면 X에서 조회한 뒤 전달을 활성화합니다. 이 과정은 1분 이내에 끝나며 여러분이 할 일은 없습니다. 응답은 두 경우 중 어느 쪽이었는지 알려줍니다.

요청

curl -X POST https://api.xsignalfeed.com/v1/monitor/targets \
  -H "Authorization: Bearer xsf_your_key" -H "Content-Type: application/json" \
  -d '{"screen_name": "elonmusk", "event_types": ["followers.verified.add"]}'

201 · 202

{
  "status": "subscribed",
  "state": "subscribed",
  "id": "44196397",
  "screen_name": "elonmusk",
  "name": "Elon Musk",
  "event_types": [
    "followers.verified.add"
  ],
  "event_types_all": false
}
{
  "status": "queued",
  "state": "queued",
  "screen_name": "newaccount",
  "user_id": null,
  "event_types": [],
  "event_types_all": true,
  "note": "target will be resolved and placed shortly; poll GET /v1/monitor/targets/{screen_name}"
}

이미 아는 계정은 즉시 구독됩니다(201, 이미 구독 중이면 200). 처음 보는 계정은 202입니다. state가 subscribed가 될 때까지 GET /v1/monitor/targets/{target}를 확인하거나, details.state가 failed이고 details.reason이 이유를 알려 주는 404를 읽으세요. 이유는 user_not_found, user_suspended, user_protected 중 하나입니다. 최근 10분 안에 X가 그렇게 알려 왔다면 POST 자체가 그 404로 응답합니다. 기본적으로 키가 허용하는 모든 이벤트 타입이 전달됩니다. 일부만 받으려면 event_types를 보내세요(예: followers.verified.add(방법)만). 한 번에 여러 개를 추가하려면 배치 엔드포인트를 사용하세요.

3 · 스트림 열기

연결하면 이벤트가 한 줄짜리 JSON으로 도착합니다. 구독 메시지도, 채널도, 그 밖에 필요한 것은 없습니다.

import asyncio, json, websockets

async def main():
    url = "wss://ws.xsignalfeed.com/v1/stream?api_key=xsf_your_key"
    async with websockets.connect(url) as ws:
        async for raw in ws:
            ev = json.loads(raw)
            if ev["t"].startswith("system."): continue
            print(ev["t"], ev["target"]["screen_name"], ev["d"].get("text", "")[:60])

asyncio.run(main())

import WebSocket from "ws";
const ws = new WebSocket("wss://ws.xsignalfeed.com/v1/stream?api_key=xsf_your_key");
ws.on("message", (raw) => {
  const ev = JSON.parse(raw);
  if (ev.t.startsWith("system.")) return;
  console.log(ev.t, ev.target.screen_name, (ev.d.text ?? "").slice(0, 60));
});

c, _, err := websocket.DefaultDialer.Dial("wss://ws.xsignalfeed.com/v1/stream?api_key=xsf_your_key", nil)
for {
    _, raw, err := c.ReadMessage()
    if err != nil { break }
    var ev Event
    json.Unmarshal(raw, &ev)
    if strings.HasPrefix(ev.T, "system.") { continue }
    log.Println(ev.T, ev.Target.ScreenName)
}

4 · 첫 이벤트 읽기

첫 프레임은 항상 system.hello입니다. 그다음부터가 실제 이벤트입니다:

스트림에 도착한 새 게시물

{
  "v": 1,
  "t": "tweet.create",
  "op": "create",
  "id": "tweet:2097879002992070835",
  "ts": 1789012345678,
  "sid": "1789012346012-0",
  "target": {
    "id": "1652541",
    "screen_name": "Reuters",
    "name": "Reuters"
  },
  "d": {
    "tweet_id": "2097879002992070835",
    "kind": "tweet",
    "text": "Ash-covered shoes and a president in crisis…",
    "lang": "en",
    "author": {
      "id": "1652541",
      "screen_name": "Reuters",
      "name": "Reuters",
      "bio": "Top and breaking news, pictures and videos from Reuters.",
      "avatar": "https://pbs.twimg.com/profile_images/1874154135869616128/nJDmubGJ_normal.jpg",
      "banner": "https://pbs.twimg.com/profile_banners/1652541/1573687397",
      "followers": 25900000,
      "following": 1150,
      "tweets": 1080000,
      "location": "Around the world",
      "url": "https://www.reuters.com",
      "verified": true,
      "verified_type": "Business",
      "protected": false,
      "created_at": "2007-03-20T17:46:05Z",
      "category": null
    },
    "reply_to": null,
    "retweet_of": null,
    "quoted": null,
    "media": [
      "https://pbs.twimg.com/media/….jpg"
    ],
    "media_items": [
      {
        "type": "photo",
        "url": "https://pbs.twimg.com/media/….jpg",
        "expanded_url": "https://x.com/Reuters/status/2097879002992070835/photo/1",
        "width": 1200,
        "height": 675
      }
    ],
    "urls": [
      "https://reut.rs/…"
    ],
    "counts": {
      "reply": 12,
      "rt": 40,
      "like": 131,
      "quote": 3,
      "bookmark": 9
    },
    "views": 20411,
    "url": "https://x.com/Reuters/status/2097879002992070835",
    "full": true,
    "kind_final": true
  }
}