### Install RoxyAPI SDK with go get

Source: https://roxyapi.com/docs/guides/feng-shui

Install the Go SDK using go get.

```bash
go get github.com/RoxyAPI/sdk-go
```

--------------------------------

### Install RoxyAPI SDK in npm, pip, composer, or dotnet

Source: https://roxyapi.com/docs/guides/angel-numbers

Install the RoxyAPI SDK for your language. Set the API key once at SDK construction; detailed setup is in the SDK install + usage guide.

```bash
npm install @roxyapi/sdk
```

```bash
pip install roxy-sdk
```

```bash
composer require roxyapi/sdk
```

```bash
dotnet add package RoxyApi.Sdk
```

--------------------------------

### Quick start with createRoxy in PHP

Source: https://roxyapi.com/docs/sdk

Quick start example for the PHP SDK. Initializes the client with `RoxyAPI\Sdk\createRoxy` and demonstrates three API calls: daily horoscope, numerology life path, and tarot Celtic Cross spread. Uses `getenv('ROXY_API_KEY')` for the API key.

```php
<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

// Daily horoscope
$horoscope = $roxy->astrology->getDailyHoroscope(sign: 'aries');

// Numerology life path
$lp = $roxy->numerology->calculateLifePath(year: 1990, month: 1, day: 15);

// Tarot Celtic Cross spread
$reading = $roxy->tarot->castCelticCross(question: 'What should I focus on this month?');
```

--------------------------------

### Set up tarot-starter-app template

Source: https://roxyapi.com/docs/tutorials/tarot-app

Clone the tarot-starter-app template, install dependencies, set the Expo public API key in .env.local, and start the development server.

```bash
git clone https://github.com/RoxyAPI/tarot-starter-app
cd tarot-starter-app
npm install
echo "EXPO_PUBLIC_ROXY_API_KEY=your_key" > .env.local
npm start
```

--------------------------------

### Quick start with RoxyClient in C#

Source: https://roxyapi.com/docs/sdk

Quick start example for the .NET SDK. Initializes the client with `new RoxyClient` and demonstrates three API calls: daily horoscope, numerology life path, and tarot Celtic Cross spread. Uses `Environment.GetEnvironmentVariable` for the API key.

```csharp
using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

// Daily horoscope
var horoscope = await roxy.Astrology.Horoscope["aries"].Daily.GetAsync();

// Numerology life path
var lp = await roxy.Numerology.LifePath.PostAsync(new() { Year = 1990, Month = 1, Day = 15 });

// Tarot Celtic Cross spread
var reading = await roxy.Tarot.Spreads.CelticCross.PostAsync(new() { Question = "What should I focus on this month?" });
```

--------------------------------

### Quick start with createRoxy in TypeScript

Source: https://roxyapi.com/docs/sdk

Quick start example for the JavaScript/TypeScript SDK. Initializes the client with `createRoxy` and demonstrates three API calls: daily horoscope, numerology life path, and tarot Celtic Cross spread. Uses `process.env.ROXY_API_KEY` for the API key.

```typescript
import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

// Daily horoscope
const { data } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' },
});

// Numerology life path
const { data: lp } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 1, day: 15 },
});

// Tarot Celtic Cross spread
const { data: reading } = await roxy.tarot.castCelticCross({
  body: { question: 'What should I focus on this month?' },
});
```

--------------------------------

### Quick start with NewRoxy in Go

Source: https://roxyapi.com/docs/sdk

Quick start example for the Go SDK. Initializes the client with `roxyapi.NewRoxy` and demonstrates three API calls: daily horoscope, numerology life path, and tarot Celtic Cross spread. Uses `os.Getenv` for the API key and notes optional parameters via pointers.

```go
import (
	"context"
	"os"

	roxyapi "github.com/RoxyAPI/sdk-go"
)

ctx := context.Background()
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))

// Daily horoscope (path param positional, optional params pointer)
horoscope, _ := roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil)

// Numerology life path (plain ints)
lp, _ := roxy.Numerology.CalculateLifePath(ctx, nil, roxyapi.CalculateLifePathJSONRequestBody{Year: 1990, Month: 1, Day: 15})

// Tarot Celtic Cross spread (optional fields via roxyapi.Ptr)
reading, _ := roxy.Tarot.CastCelticCross(ctx, nil, roxyapi.CastCelticCrossJSONRequestBody{Question: roxyapi.Ptr("What should I focus on this month?")})
```

--------------------------------

### Quick start with create_roxy in Python

Source: https://roxyapi.com/docs/sdk

Quick start example for the Python SDK. Initializes the client with `create_roxy` and demonstrates three API calls: daily horoscope, numerology life path, and tarot Celtic Cross spread. Uses a placeholder API key string.

```python
from roxy_sdk import create_roxy

roxy = create_roxy("your-api-key")

# Daily horoscope
horoscope = roxy.astrology.get_daily_horoscope(sign="aries")

# Numerology life path
lp = roxy.numerology.calculate_life_path(year=1990, month=1, day=15)

# Tarot Celtic Cross spread
reading = roxy.tarot.cast_celtic_cross(question="What should I focus on this month?")
```

--------------------------------

### Connect with MCP Python SDK (short example)

Source: https://roxyapi.com/docs/mcp?product=chinese-astrology

A shorter Python example that connects to the RoxyAPI Chinese Astrology MCP server and lists available tools. Requires the mcp package (pip install mcp).

```python
// Python — pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/chinese-astrology",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())
```

--------------------------------

### Clone and run the ai-spiritual-companion template

Source: https://roxyapi.com/docs/tutorials/ai-companion-with-memory

Clone and run the ai-spiritual-companion template. Fills in the .env.local keys after copying the example file, then starts the development server.

```bash
git clone https://github.com/RoxyAPI/ai-spiritual-companion
cd ai-spiritual-companion
npm install
npx supabase start
cp .env.example .env.local   # then fill in the keys, each one is commented
npm run dev
```

--------------------------------

### Python minimal connection example

Source: https://roxyapi.com/docs/mcp?product=crystals

A shorter Python example using the MCP Python SDK to connect and list tools. Requires the mcp package (pip install mcp).

```python
// Python — pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/crystals",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())
```

--------------------------------

### Python MCP client example (from TypeScript section)

Source: https://roxyapi.com/docs/mcp?product=human-design

This Python example appears in the TypeScript section as a comment. It connects to the RoxyAPI MCP server and lists available tools. Requires 'pip install mcp'.

```python
// Python — pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/human-design",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())
```

--------------------------------

### Install RoxyAPI UI with npm, bun, or CDN

Source: https://roxyapi.com/docs/sdk

Install the RoxyAPI UI package alongside the SDK using npm or bun, or load the UI from the CDN. The CDN script tag is also used in the vanilla HTML and WordPress examples.

```bash
npm install @roxyapi/ui @roxyapi/sdk
```

```bash
bun add @roxyapi/ui @roxyapi/sdk
```

```html
<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>
```

--------------------------------

### Python MCP client (short version)

Source: https://roxyapi.com/docs/mcp?product=astrology

Shorter Python example that connects to the RoxyAPI MCP server and lists available tools. Requires pip install mcp.

```python
// Python — pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/astrology",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())
```

--------------------------------

### Connect to RoxyAPI MCP with Python SDK (list tools only)

Source: https://roxyapi.com/docs/mcp?product=dreams

Alternative Python example using the MCP Python SDK to connect and list tools. Requires the 'mcp' package (pip install mcp). This snippet only lists tools and does not call any tools.

```python
// Python — pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/dreams",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())
```

--------------------------------

### Connect to RoxyAPI MCP with Python SDK (list tools only)

Source: https://roxyapi.com/docs/mcp?product=mesoamerican-astrology

Alternative Python example that connects to the RoxyAPI Mesoamerican Astrology server and lists available tools. Requires the mcp package (pip install mcp).

```python
// Python — pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/mesoamerican-astrology",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())
```

--------------------------------

### Clone and run a RoxyAPI template

Source: https://roxyapi.com/docs/templates

Clone the tarot starter app, install dependencies, copy the environment template, add your API key, and start the app. This is the standard workflow for using any RoxyAPI template.

```bash
git clone https://github.com/RoxyAPI/tarot-starter-app.git
cd tarot-starter-app
npm install
cp .env.example .env
# Add your API key to .env
npm start
```

--------------------------------

### Use RoxyAPI MCP with OpenAI Agents SDK

Source: https://roxyapi.com/docs/mcp?product=forecast

Connect to the RoxyAPI Forecast MCP server using the OpenAI Agents SDK's MCPServerStreamableHttp. Requires the openai-agents package (pip install openai-agents). The example runs an agent that gets today's horoscope for Aries.

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="RoxyAPI",
        params={
            "url": "https://roxyapi.com/mcp/forecast",
            "headers": {"X-API-Key": "your_api_key_here"}
        }
    ) as server:
        agent = Agent(
            name="Assistant",
            instructions="Use RoxyAPI tools to answer questions",
            mcp_servers=[server]
        )
        result = await Runner.run(agent, "Get today's horoscope for Aries")
        print(result.final_output)

asyncio.run(main())

# pip install openai-agents
```

--------------------------------

### OpenAI Agents SDK with MCPServerStreamableHttp (Python)

Source: https://roxyapi.com/docs/mcp?product=astrology

Use the OpenAI Agents SDK with MCPServerStreamableHttp to connect to the RoxyAPI Astrology MCP server. Requires `pip install openai-agents`. The example shows an async main function that runs an agent to get today's horoscope for Aries.

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="RoxyAPI",
        params={
            "url": "https://roxyapi.com/mcp/astrology",
            "headers": {"X-API-Key": "your_api_key_here"}
        }
    ) as server:
        agent = Agent(
            name="Assistant",
            instructions="Use RoxyAPI tools to answer questions",
            mcp_servers=[server]
        )
        result = await Runner.run(agent, "Get today's horoscope for Aries")
        print(result.final_output)

asyncio.run(main())
```

--------------------------------

### Set up a new project for from-scratch chatbot

Source: https://roxyapi.com/docs/tutorials/ai-chatbot

Commands to create a new directory, initialize a Node.js project, and install the Anthropic SDK and RoxyAPI SDK.

```bash
mkdir astro-chat && cd astro-chat
npm init -y
npm install @anthropic-ai/sdk @roxyapi/sdk
```

--------------------------------

### Get Devata Details with curl

Source: https://roxyapi.com/docs/guides/vastu

GET /vastu/devatas/{id} returns a single devata row. The example fetches the Brahma devata and shows its squares, pada count, verses, and role.

```bash
curl https://roxyapi.com/api/v2/vastu/devatas/brahma -H "X-API-Key: $ROXY_API_KEY"
# => squares [31,32,33,40,41,42,49,50,51], padaCount 9, verses ["53.46"],
#    role "The devata Brahmā holds the nine central squares of the mandala."
```

--------------------------------

### Build an AI spiritual companion with per-user memory on RoxyAPI

Source: https://roxyapi.com/docs/prompts

Instructions for building the companion, including reading documentation, cloning the template, and running locally. Key steps: clone the template, set up environment variables, and run the development server. The verification command 'npm run verify' is the gate before any push.

```text
Build an AI spiritual companion with per-user memory on RoxyAPI. Before any code: read https://roxyapi.com/AGENTS.md in full, search https://roxyapi.com/mcp/docs (tool: search_docs) for anything you are unsure of, and read https://roxyapi.com/docs/tutorials/ai-chat-widgets.md for how a tool result becomes a drawn chart.

## Fastest path: the template
git clone https://github.com/RoxyAPI/ai-spiritual-companion, then follow its README and AGENTS.md. Next.js, TypeScript, Supabase (magic link auth, four tables under row level security, pgvector for recall), Vercel AI SDK, Remote MCP, MIT. Local run: npx supabase start, npx supabase db reset, copy .env.example to .env.local and fill ROXY_API_KEY, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, LLM_PROVIDER and the key for that provider, then npm run dev. npm run verify is the gate before any push. Customize the voices, the enabled domains (ROXYAPI_MCP_PRODUCTS), the onboarding copy and the palette. Stop here unless I asked for a build inside my own app.

## What makes it a companion, keep all of it
1. Onboarding once: birth date, time and city. City is an autocomplete on GET /location/search that resolves coordinates and the IANA timezone silently.
2. The natal chart is computed exactly once per account with POST /astrology/natal-chart through the typed SDK, stored as JSON, and read from the database afterwards. The natal chart tool is withheld from the model so it cannot recompute it; the chart is in the system prompt every turn.
3. Everything else is Remote MCP: servers at https://roxyapi.com/mcp/{domain}, X-API-Key on the transport, compact: true on every call, a small default domain list widened by env.
4. Every reading the companion shows is appended to a readings table with the calculation it was grounded in. Past turns are embedded and searched by meaning, so asking about a feeling finds the turn where it was first described.
5. Privacy split you can state to users: only birth date, time and coordinates are ever sent to be calculated. Journal entries, moods and conversation text stay in the operator database.
6. Per-user spend limits counted off the readings table, not in memory, so they hold on serverless hosts.
7. Every tool result is drawn with componentForTool from @roxyapi/ui-react; the stored chart is drawn with RoxyNatalChart on its own page.
8. Prove it: create an account locally, complete onboarding for a named city, ask two questions on different days, and show that the second answer recalled the first.
```

--------------------------------

### Install RoxyAPI SDKs (Python, PHP, C#)

Source: https://roxyapi.com/docs/tutorials/ai-companion-with-memory

Install the RoxyAPI SDKs for Python, PHP, and C#. These follow the same shape as the npm SDK.

```bash
pip install roxy-sdk
```

```bash
composer require roxyapi/sdk
```

```bash
dotnet add package RoxyApi.Sdk
```

--------------------------------

### Install RoxyAPI SDK via dotnet

Source: https://roxyapi.com/docs/guides/crystals

Install the RoxyAPI SDK for .NET projects.

```bash
dotnet add package RoxyApi.Sdk
```

--------------------------------

### Use OpenAI Agents SDK with MCPServerStreamableHttp

Source: https://roxyapi.com/docs/mcp?product=ayurveda

Python example using the OpenAI Agents SDK to connect to the Ayurveda MCP server. Requires `pip install openai-agents`. Pass your API key in the headers; the example runs an agent that fetches today's horoscope for Aries.

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="RoxyAPI",
        params={
            "url": "https://roxyapi.com/mcp/ayurveda",
            "headers": {"X-API-Key": "your_api_key_here"}
        }
    ) as server:
        agent = Agent(
            name="Assistant",
            instructions="Use RoxyAPI tools to answer questions",
            mcp_servers=[server]
        )
        result = await Runner.run(agent, "Get today's horoscope for Aries")
        print(result.final_output)

asyncio.run(main())
```

--------------------------------

### Agent Prompt Example

Source: https://roxyapi.com/docs/mcp?product=kabbalah

Example prompt to use with your agent once the server is connected.

```text
Using roxy-kabbalah, help me add the Kabbalah endpoints to my app.
```

--------------------------------

### List Hebrew letters with GET /kabbalah/letters

Source: https://roxyapi.com/docs/guides/kabbalah

Use this curl command to get the full Hebrew alphabet with 22 rows, including total, classCounts, and letterAttribution. The example uses the 'golden-dawn' attribution, and the response shows classCounts (mother, double, simple) and the first letter's details. There is no pagination.

```bash
curl "https://roxyapi.com/api/v2/kabbalah/letters?letterAttribution=golden-dawn" \
  -H "X-API-Key: $ROXY_API_KEY"
# => total 22, classCounts { mother: 3, double: 7, simple: 12 },
#    letters[0] { id: "alef", letter: "א", value: 1, letterClass: "mother",
#                 attribution: { kind: "element", value: "air" },
#                 trump: { id: "fool", name: "The Fool" }, path: 11 }
```

--------------------------------

### RoxyAPI agent instructions for AGENTS.md / CLAUDE.md

Source: https://roxyapi.com/docs/integrations/nextjs

Drop this into AGENTS.md or CLAUDE.md at the repo root so coding agents start with RoxyAPI conventions: base URL, X-API-Key auth from process.env.ROXY_API_KEY (server side only), the order of truth (docs MCP, AGENTS.md, OpenAPI spec, llms.txt), and rules like using @roxyapi/sdk typed methods, TypeScript strict, no any, never calling from a 'use client' file, and resolving a birthplace with GET /location/search?q={city} before any chart call.

```markdown
RoxyAPI: one REST API for astrology, Vedic astrology, forecasting, human design, numerology, tarot and 18+ insight domains on one key. Base URL https://roxyapi.com/api/v2. Auth is the X-API-Key header, read from process.env.ROXY_API_KEY, server side only.

Where the truth lives, in this order:
1. The docs MCP server at https://roxyapi.com/mcp/docs. Streamable HTTP, no key, one tool: search_docs. Search it before every endpoint, field, SDK method and integration step.
2. https://roxyapi.com/AGENTS.md, read in full before any code. Auth rules, the location-first rule, request body shapes, the error contract, field formats, domain gotchas.
3. The OpenAPI spec at https://roxyapi.com/api/v2/openapi.json, every domain in one document: query it with the jq recipe in AGENTS.md, never read it whole. Generate types for one domain from that domain spec, never hand-write a response interface:
   npx openapi-typescript https://roxyapi.com/api/v2/astrology/openapi.json -o src/api/schema.ts
4. No MCP available? Fetch https://roxyapi.com/llms.txt instead.

Rules: npm install @roxyapi/sdk and use its typed methods rather than hand-rolled fetch. TypeScript strict, no any. Never call RoxyAPI from a 'use client' file. Resolve a birthplace with GET /location/search?q={city} before any chart call and pass its timezone through.
```

--------------------------------

### Install Roxy API SDK (npm, pip, Composer, CDN)

Source: https://roxyapi.com/docs/tutorials/horoscope-widget

Install the Roxy API SDK using npm, pip, Composer, or the CDN script tag. Choose the path that matches your environment.

```bash
npm install @roxyapi/sdk
```

```bash
pip install roxy-sdk
```

```bash
composer require roxyapi/sdk
```

```html
<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0/dist/cdn/roxy-ui.js"></script>
```

--------------------------------

### curl request with lang parameter

Source: https://roxyapi.com/docs/guides/ayurveda

Example POST request to the ritucharya endpoint with lang=de to get a German response. Requires an API key stored in the ROXY_API_KEY environment variable.

```bash
curl -X POST "https://roxyapi.com/api/v2/ayurveda/ritucharya?lang=de" \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"date":"2026-03-01"}'
```

--------------------------------

### Clone and Initialize Astrology Starter App

Source: https://roxyapi.com/docs/tutorials/dating-app

Commands to clone the React Native astrology starter repository, install dependencies, configure the API key, and start the development server.

```bash
git clone https://github.com/RoxyAPI/astrology-starter-app
cd astrology-starter-app
npm install
echo "EXPO_PUBLIC_ROXY_API_KEY=your_key" > .env.local
npm start
```

--------------------------------

### Connect using Python SDK

Source: https://roxyapi.com/docs/mcp?product=kabbalah

Example of connecting to the MCP server using the Python SDK.

```python
# Python — pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client(
        "https://roxyapi.com/mcp/kabbalah",
        headers={"X-API-Key": "your_api_key_here"}
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

asyncio.run(main())
```

--------------------------------

### API response: Daily horoscope JSON

Source: https://roxyapi.com/docs/integrations/bolt

Example response from GET /astrology/horoscope/{sign}/daily. It returns horoscope details, events, lucky number, and more. Use this to verify the API response structure.

```json
{
  "sign": "aries",
  "date": "2026-09-10",
  "overview": "...",
  "love": "...",
  "career": "...",
  "health": "...",
  "finance": "...",
  "advice": "...",
  "column": "...",
  "events": [
    {
      "type": "sign-ingress",
      "at": "2026-09-10T16:21:14Z",
      "bodies": ["Mercury"],
      "sign": "libra",
      "house": 7,
      "through": "2026-09-30T11:44:42Z"
    }
  ],
  "luckyNumber": 9,
  "luckyColor": "Red",
  "moonSign": "Virgo",
  "moonPhase": "Waning Crescent Moon",
  "energyRating": 4
}
```