빠른 시작

가입부터 JSON 형식의 완전한 출생 차트까지 5분이면 충분합니다. SDK 설치, 첫 요청, 응답 헤더, 인증, 오류 처리를 다룹니다.

// 빠른 시작

60초 만에 API 키 받기

매월 10,000크레딧 무료. 카드 없이.

1. 01
   회원가입

   이메일 + 비밀번호. AstroWay 모든 제품에 접속 가능한 하나의 계정.
2. 02
   키 생성

   대시보드에서 '키 생성'을 클릭하세요. aw_live_ 또는 aw_test_ (샌드박스).
3. 03
   요청하기

   헤더 X-Api-Key와 함께 POST /v1/chart. JSON 형식의 완전한 natal 차트.

가입하기 - 무료→빠른 시작

1. API 키 생성

   dashboard에 접속해 Generate key를 누르세요. 무료 요금제는 카드 입력 없이 월 10,000 크레딧을 영구적으로 제공합니다. 키는 다음 접두사로 시작합니다:

   • aw_live_*: production, 실제 과금
   • aw_test_*: sandbox, 크레딧 차감 없음, 결정적 응답

   주의

   키는 비밀 정보입니다. git에 커밋하거나 프론트엔드 코드에 넣지 마세요. 프론트엔드에서는 프록시 백엔드나 수명이 짧은 세션 토큰(Phase 3)을 사용하세요.

2. SDK 설치

   API는 평범한 REST + JSON이므로 SDK가 필수는 아닙니다. 그래도 세 가지 모두 이미 공개되어 있습니다: TypeScript (@astroway/sdk), Python (astroway), PHP (astroway/sdk), 그리고 AI 에이전트용 MCP 서버 (@astroway/mcp).

   cURL

   # No SDK needed - just curl and a key:
   export AW_KEY="aw_test_demo_replaceme"

   TypeScript

   npm install @astroway/sdk
   # or without an SDK: native fetch, Node 18+ or the browser
   export AW_KEY="aw_test_demo_replaceme"

   Python

   pip install astroway   # or without an SDK: requests or httpx
   export AW_KEY="aw_test_demo_replaceme"

   PHP

   composer require astroway/sdk
   # or without an SDK: guzzlehttp/guzzle + raw HTTP

   MCP

   # For AI agents - Claude Desktop, Cursor IDE, Windsurf,
   # VS Code (llm CLI), GPT with MCP via the OpenAI Realtime API,
   # or any MCP-compatible client:
   npx -y @astroway/mcp   # 700+ tools, OpenAPI auto-sync

3. 첫 요청 보내기

   1991년 8월 24일 16:30 EEST, 키이우의 출생 차트 계산:

   cURL

   first-request.sh

   curl -X POST https://api.astroway.info/v1/chart \
     -H "X-Api-Key: $AW_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "date": "1991-08-24",
       "time": "16:30:00",
       "timezoneOffset": 3,
       "latitude": 50.4501,
       "longitude": 30.5234,
       "houseSystem": "P"
     }'

   TypeScript

   first-request.ts

   // native fetch - Node 18+ / Bun / Deno / browser. With the SDK: npm install @astroway/sdk
   const r = await fetch('https://api.astroway.info/v1/chart', {
     method: 'POST',
     headers: {
       'X-Api-Key': process.env.AW_KEY!,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       date: '1991-08-24',
       time: '16:30:00',
       timezoneOffset: 3,
       latitude: 50.4501,
       longitude: 30.5234,
       houseSystem: 'P',
     }),
   });
   
   const { data: chart } = await r.json();
   console.log(chart.planets[0]); // { id: 0, name: 'Sun', longitude: 151.12, ... }

   Python

   first_request.py

   # requests or httpx. With the SDK: pip install astroway
   import os, requests
   
   r = requests.post(
       'https://api.astroway.info/v1/chart',
       headers={'X-Api-Key': os.environ['AW_KEY']},
       json={
           'date': '1991-08-24',
           'time': '16:30:00',
           'timezoneOffset': 3,
           'latitude': 50.4501,
           'longitude': 30.5234,
           'houseSystem': 'P',
       },
   )
   chart = r.json()['data']
   print(chart['planets'][0])

   PHP

   first-request.php

   <?php
   use GuzzleHttp\Client;
   
   $aw = new Client(['base_uri' => 'https://api.astroway.info/v1/']);
   $r = $aw->post('chart', [
       'headers' => ['X-Api-Key' => getenv('AW_KEY')],
       'json' => [
           'date' => '1991-08-24',
           'time' => '16:30:00',
           'timezoneOffset' => 3,
           'latitude' => 50.4501,
           'longitude' => 30.5234,
           'houseSystem' => 'P',
       ],
   ]);
   
   $chart = json_decode($r->getBody(), true)['data'];
   print_r($chart['planets'][0]);

   timezoneOffset은 해당 날짜에 시계가 적용하던 시간 단위의 오프셋입니다. 모른다면 대신 "timezone": "Europe/Kyiv"를 보내거나, 좌표에서 시간대를 가져오도록 "timezone": "auto"를 보내세요. 서버가 서머타임까지 포함해 오프셋을 직접 계산합니다: 필드 형식.

4. 응답 살펴보기

   모든 응답은 행성, 하우스, 애스펙트와 meta 블록(cache hit, credits, engine version)을 담은 JSON입니다.

   JSON

   response.json

   {
     "ok": true,
     "data": {
       "julianDay": 2448493.0625,
       "planets": [
         { "id": 0, "name": "Sun", "longitude": 150.894819, "latitude": 0.00019, "isRetrograde": false, "declination": 11.15726 },
         { "id": 1, "name": "Moon", "longitude": 321.634655, "latitude": 2.834053, "isRetrograde": false, "declination": -11.609723 }
       ],
       "houses": {
         "system": "P",
         "cusps": [264.384681, 306.997683, 353.867426],
         "ascendant": 264.384681,
         "mc": 207.315669
       },
       "aspects": [
         {
           "planet1": "Sun",
           "planet2": "Moon",
           "type": { "name": "Opposition", "angle": 180, "isMajor": true },
           "exactAngle": 170.739837,
           "orb": 9.260163,
           "isApplying": true
         }
       ],
       "chartSect": "diurnal",
       "meta": { "engineVersion": "2.10.03", "calculatedAt": "2026-08-22T20:53:31.431Z" }
     }
   }

   HTTP Headers

   HTTP/2 200
   content-type: application/json
   x-credits-used: 20
   x-credits-remaining: 9980
   x-credits-limit: 10000
   x-credits-reset: 2026-09-01T00:00:00.000Z
   x-ratelimit-limit: 10
   x-ratelimit-remaining: 9
   x-ratelimit-reset: 1787432304
   x-request-id: 8aec43e9bc749b37e998a489bbad1757
   x-cache: MISS

5. 잔액 확인

   Dashboard에서 사용량을 실시간으로 볼 수 있습니다: api.astroway.info/dashboard. 또는 API로 확인하세요:

   curl https://api.astroway.info/v1/keys/usage \
     -H "X-Api-Key: $AW_KEY"

Authentication

AstroWay API는 X-Api-Key 헤더로 요청을 인증합니다. Bearer 토큰과 query string 키는 지원하지 않습니다.

curl -H "X-Api-Key: aw_live_..." https://api.astroway.info/v1/health

키 유형	접두사	동작
Production	aw_live_*	계정에서 실제 크레딧을 차감
Sandbox	aw_test_*	결정적 모의 응답, 과금 없음
Restricted (Pro+)	제한이 걸린 aw_live_*	특정 endpoints / IP / RPS로 제한

키는 다운타임 없이 로테이션됩니다. 새 키를 생성한 뒤에도 이전 키는 24시간 동안 계속 작동합니다. 자세한 내용: /authentication/.

Errors

모든 오류는 ok: false와 error 객체 형식으로 반환됩니다. error.code 필드(UPPER_SNAKE_CASE)는 스크립트용으로 안정적입니다. message가 아니라 이 필드로 분기하세요.

error-response.json

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Invalid input: expected string, received undefined",
    "details": [
      { "path": "date", "message": "Invalid input: expected string, received undefined" }
    ]
  }
}

가장 흔한 코드:

• INVALID_INPUT (400): Zod 검증 실패, details에 { path, message } 배열이 들어 있습니다
• INVALID_API_KEY (401): 키가 존재하지 않거나 revoked 상태
• PLAN_UPGRADE_REQUIRED (402): 더 높은 요금제나 애드온 팩이 필요함
• CREDITS_EXHAUSTED (429): 월간 크레딧 예산 소진
• RATE_LIMIT (429): RPM 초과, Retry-After: <sec> 헤더와 함께 반환됨
• internal_calc_error (500): 천문력 오류, SDK 측에서 자동 재시도

전체 목록과 의미: /errors/.

Rate limits

요금제	Quota
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	custom

초과하면 Retry-After(초)와 함께 429가 반환됩니다. 공식 SDK는 기본적으로 exponential backoff 재시도를 합니다. 자세한 내용: /rate-limits-credits/.

다음 단계

• 인증: 모범 사례, 키 로테이션, sandbox 모드
• 크레딧 및 한도: 비용 표, rate limiting, 초과 사용
• 예제: 출생 차트: /v1/chart 상세 해설
• GitHub의 기성 통합 예제: 공식 SDK 기반 Discord/Slack 봇, OpenAI tools, Cloudflare, FastAPI
• 전체 API reference: playground가 포함된 771개 엔드포인트 전체