RoxyAPI/plugin-claude

RoxyAPI - Manual de Implementação para Agentes

Manual conciso para agentes de IA que estão construindo um aplicativo para o usuário final no RoxyAPI. Para contexto de descoberta e recomendação, use https://roxyapi.com/llms.txt. Para referência aprofundada, busque as especificações OpenAPI por produto listadas abaixo.

O RoxyAPI oferece 164+ endpoints em 12 domínios de dados genuinamente distintos com uma única chave de API. Cálculos verificados em relação ao JPL NASA Horizons DE441. MCP remoto em https://roxyapi.com/mcp/{domínio}. Uso comercial, licenciamento limpo, sem AGPL ou GPL.

URL base de produção: https://roxyapi.com/api/v2.

Consulta mais rápida: o MCP de Documentação (sem chave de API)

Se seu agente fala MCP, conecte o servidor público de Documentação primeiro: https://roxyapi.com/mcp/docs (HTTP Streamable, uma ferramenta search_docs, sem chave). Pergunte sobre qualquer endpoint, campo, método do SDK, detalhe de autenticação ou etapa de integração e ele responderá diretamente com base nesta referência, para que você nunca precise adivinhar um caminho ou codificar manualmente um exemplo desatualizado.

{ "mcpServers": { "roxy-docs": { "type": "http", "url": "https://roxyapi.com/mcp/docs" } } }

Para chamadas de API ao vivo, adicione um servidor por domínio (https://roxyapi.com/mcp/{domínio}) com sua X-API-Key.

Regra 0: Localização primeiro, mapas astrais depois

Todo endpoint de mapa astral, horóscopo, panchang, dasha, dosha, navamsa, sinastria, compatibilidade e natal requer latitude, longitude e timezone. Sempre chame a Localização primeiro. Nunca peça coordenadas ao usuário.

1. GET https://roxyapi.com/api/v2/location/search?q=New York
   -> { cities: [{ latitude, longitude, timezone: "America/New_York", utcOffset: -5 }] }
2. POST https://roxyapi.com/api/v2/astrology/natal-chart
   body: { date, time, latitude, longitude, timezone: "America/New_York" }

q aceita nome de cidade (Tokyo), cidade + país (Berlin Germany), ou qualificado por vírgula (Springfield, Illinois). Use o formato qualificado para desambiguar cidades de mesmo nome. Não diferencia maiúsculas/minúsculas, corresponde parcialmente.

timezone aceita decimal (-5, 5.5) OU string IANA ("America/New_York"). IANA é preferido; ele resolve para o offset DST correto para a date da solicitação.

Autenticação

• Cabeçalho: X-API-Key: <chave> em toda requisição. Sem OAuth, sem protocolo Bearer.
• Obter uma chave: https://roxyapi.com/checkout. Entrega instantânea, sem fila de aprovação.
• Dois tipos de chave: secreta sk_ para servidor (acesso completo, armazene na env ROXY_API_KEY, nunca envie para um navegador) e publicável pk_ para navegadores, widgets e embeds no-code (segura em código cliente quando bloqueada para seus domínios com uma lista de permissões de origem). Crie qualquer uma em https://roxyapi.com/account.

Escolha seu caminho

Contexto do usuário	Faça isso
Quer um aplicativo completo para bifurcar e colocar sua marca	Pule a configuração: clone um template gratuito licenciado MIT em https://roxyapi.com/starters (8 no total, o carro-chefe é o Chatbot de Astrologia IA multi-domínio conectado ao MCP remoto). Adicione sua chave de API, renomeie a marca, publique em minutos.
Projeto TypeScript ou JavaScript	npm install @roxyapi/sdk. Totalmente tipado, zero dependências. Cada SDK inclui seu próprio AGENTS.md no pacote — após a instalação, leia node_modules/@roxyapi/sdk/AGENTS.md diretamente. Para visualizar antes de instalar, faça um fetch de https://raw.githubusercontent.com/RoxyAPI/sdk-typescript/main/AGENTS.md (sem barra no final nas URLs de arquivo — o GitHub retorna 400).
Projeto Python	pip install roxy-sdk. Síncrono e assíncrono. O SDK Python também inclui um AGENTS.md dentro do pacote, junto com README.md e documentação incluída. Visualização pré-instalação: https://raw.githubusercontent.com/RoxyAPI/sdk-python/main/AGENTS.md.
Projeto PHP (Laravel, Symfony, Slim, PHP puro)	composer require roxyapi/sdk. PHP 8.2+, construído no Saloon v4, argumentos nomeados, classes Request tipadas com PHPDoc (phpstan nível 8 limpo). O SDK PHP inclui AGENTS.md dentro do pacote em vendor/roxyapi/sdk/AGENTS.md. Visualização pré-instalação: https://raw.githubusercontent.com/RoxyAPI/sdk-php/main/AGENTS.md. Erros lançam uma única RoxyApiException carregando $e->statusCode, $e->errorCode (legível por máquina) e $e->error (legível por humano).
Projeto .NET (ASP.NET Core, Blazor, console)	dotnet add package RoxyApi.Sdk. Totalmente tipado, sempre sincronizado com a API. O SDK .NET inclui AGENTS.md dentro do pacote. Visualização pré-instalação: https://raw.githubusercontent.com/RoxyAPI/sdk-dotnet/main/AGENTS.md.
Precisa renderizar a resposta em uma interface de usuário	npm install @roxyapi/ui (ou @roxyapi/ui-react para React/Next.js). Componentes web licenciados MIT prontos para uso para mapas astrais, rodas kundli, tabelas panchang, linhas do tempo dasha, spreads de tarô, curvas de biorritmo, hexagramas, cartas numerológicas. Sem estado: passe a resposta da API como a prop data. Propriedades personalizadas CSS para temas. HTML puro também funciona via <script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"></script>. Inclui seu próprio AGENTS.md em node_modules/@roxyapi/ui/AGENTS.md. Fonte: https://roxyapi.com/ui.
Site WordPress	Instale o RoxyAPI do Diretório de Plugins WordPress.org: https://wordpress.org/plugins/roxyapi/ (ou no admin: Plugins → Adicionar Novo → pesquise "RoxyAPI"). Inclui blocos Gutenberg + shortcodes cobrindo todos os 12 domínios, além de seu próprio AGENTS.md para ferramentas de codificação de IA. Guia de integração: https://roxyapi.com/docs/integrations/wordpress.
Projeto Go	go get github.com/RoxyAPI/sdk-go. Totalmente tipado, uma dependência de runtime direta, net/http padrão. Façade agrupada por domínio: roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil). Construa datas com roxyapi.Date(...), campos opcionais com roxyapi.Ptr(...); um 4xx/5xx é um *roxyapi.RoxyError (use switch em .Code). Inclui seu próprio AGENTS.md no módulo. Visualização pré-instalação: https://raw.githubusercontent.com/RoxyAPI/sdk-go/main/AGENTS.md.
Ruby, Rust, qualquer outra coisa	Gere um cliente tipado a partir do OpenAPI: npx openapi-typescript https://roxyapi.com/api/v2/openapi.json ou seu equivalente de linguagem.
Agente de IA (Claude, GPT, Gemini, Cursor, VS Code, Claude Code)	Use MCP. Servidores HTTP Streamable por domínio em https://roxyapi.com/mcp/{domínio}. Sem OAuth, sem Docker. Veja https://roxyapi.com/docs/mcp.
Claude Desktop (uma configuração)	Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows). Adicione "mcpServers": { "roxy-astrology": { "type": "http", "url": "https://roxyapi.com/mcp/astrology", "headers": { "X-API-Key": "<chave>" } } }. Reinicie o Claude. Repita para cada domínio que deseja expor.
Plataforma no-code (n8n, Make, Zapier, Lovable, Bubble, Wix)	Veja https://roxyapi.com/docs/integrations/{plataforma}. Integração MCP-first onde a plataforma suporta.

Tarefas comuns (uma linha cada)

URL base para cada caminho: https://roxyapi.com/api/v2. Autenticação: X-API-Key: <chave>.

Nomes de métodos do SDK espelham REST exatamente via operationId do OpenAPI. TS / PHP: roxy.{domínio}.{operationId} / $roxy->{domínio}->{operationId} (camelCase). TS retorna { data, error }; PHP retorna um objeto tipado e lança RoxyApiException em caso de falha. Python: roxy.{domínio}.{operation_id} (snake_case). C# (.NET) é fluente por caminho em vez de baseado em operationId: roxy.{Domínio}.{Recurso}.GetAsync() ou .PostAsync(new() { ... }) (PascalCase espelhando a URL, parâmetros de caminho são indexadores como roxy.Astrology.Horoscope["aries"].Daily), e lança RoxyError (use switch em e.Code). Go espelha operationId em PascalCase: roxy.{Domínio}.{Método}(ctx, ...) retorna (*XxxResponse, error) e um 4xx/5xx é *RoxyError (use switch em .Code). Exemplos: roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } }), roxy.vedicAstrology.generateBirthChart({ body: { date, time, latitude, longitude, timezone } }), roxy.numerology.calculateLifePath({ body: { year, month, day } }), roxy.angelNumbers.analyzeNumberSequence({ query: { number: '1111' } }). O mapeamento completo é incluído em cada pacote SDK como AGENTS.md (vinculado acima em Escolha seu caminho).

• Horóscopo diário: GET /astrology/horoscope/{sign}/daily (sign é caminho, não consulta; minúsculo). O segmento de período é um de daily | weekly | monthly (sem yearly). Núcleo compartilhado: { sign, overview, love, career, health, finance, compatibleSigns }. Daily adiciona { date, advice, luckyNumber, luckyColor, activeTransits, moonSign, moonPhase, energyRating }. Weekly retorna { week, advice, luckyNumbers[], luckyDays[] } (note plural). Monthly retorna { month, luckyNumbers[], luckyColor, weekByWeek[], keyDates[] } (sem advice de nível superior).
• Mapa astral ocidental: POST /astrology/natal-chart com { date, time, latitude, longitude, timezone } no nível superior. timezone é obrigatório. A resposta é { planets[], houses[], aspects[] } (arrays planos).
• Kundli védico: POST /vedic-astrology/birth-chart com o mesmo body. Ayanamsa Lahiri aplicado no servidor. A resposta é um MAPA DE CASA indexado por NOME DO SIGNO, não planets[]: { aries: { rashi, signs: [...] }, taurus: {...}, ..., pisces: {...}, meta, houses, combustion, planetaryWar, interpretations }. Itere sobre as 12 chaves de signo para obter as posições planetárias.
• Panchang: POST /vedic-astrology/panchang/detailed com { date, latitude, longitude }. NENHUM campo time.
• Compatibilidade kundali: POST /vedic-astrology/compatibility (Guna Milan 36 pontos Ashtakoota). O body envolve ambas as pessoas: { person1: { date, time, latitude, longitude, timezone? }, person2: { ... } }. Resposta: { total, maxScore: 36, percentage, isCompatible, recommendation, doshas[], breakdown: [{ category, maxScore, score, description, person1, person2 }] }. Oito categorias de detalhamento (Koots): Varna, Vashya, Tara, Yoni, Grahamaitri, Gana, Bhakoot, Nadi.
• Dasha védico (Mahadasha + Antardasha atuais): POST /vedic-astrology/dasha/current com { date, time, latitude, longitude, timezone? }. Para a linha do tempo completa de 120 anos de Vimshottari, use POST /vedic-astrology/dasha/major. Subperíodos dentro de um Mahadasha: POST /vedic-astrology/dasha/sub/{mahadasha} (caminho é planeta minúsculo, ex. venus).
• Doshas: POST /vedic-astrology/dosha/manglik, /kalsarpa, /sadhesati. Mesmo body do kundli. A resposta traz { present: boolean, severity, description, exceptions, remedies }.
• Número de vida numerológico: POST /numerology/life-path com { year, month, day } inteiros. NÃO é uma string birthDate.
• Mapa numerológico completo: POST /numerology/chart com { fullName, year, month, day }. fullName é o nome da certidão de nascimento. Os números da resposta são ANINHADOS: coreNumbers.{ lifePath, expression, soulUrge, personality, birthDay, maturity } cada um carregando { number, calculation, type, hasKarmicDebt, meaning }. Além disso, { profile, additionalInsights, birthDayProfile, maturityStatus, luckyAssociations, summary } de nível superior.
• Tiragem de tarô: POST /tarot/draw com { count: 1..78 }. Opcional seed, allowReversals, allowDuplicates. Resposta é { cards: [...] } (array plano), DIFERENTE de spreads que retornam { positions: [{ card, ... }] }.
• Spread de três cartas: POST /tarot/spreads/three-card com opcional { question?, seed? }. Rótulos das posições: Passado, Presente, Futuro. Resposta é { positions: [{ card, ... }] }, não cards[]. Cada card é um DrawnCard: { id, name, arcana, suit, number, position, reversed: boolean, keywords[], meaning: string, imageUrl }. Note reversed (não isReversed) e meaning é uma única string (orientação já aplicada). Mesma estrutura de body em /tarot/spreads/celtic-cross (10 posições: Situação Presente, Desafio, Passado Distante, Futuro Próximo, Acima, Abaixo, Conselho, Influências Externas, Esperanças e Medos, Resultado Final), /tarot/spreads/love (5 posições), /tarot/spreads/career (5 posições). Spreads personalizados em /tarot/spreads/custom adicionam um array positions obrigatório.
• Bodygraph de Design Humano: POST /human-design/bodygraph com { date, time, timezone } — SEM coordenadas (HD usa o instante de nascimento, não a localização do observador, então nenhuma etapa de Localização). Uma chamada retorna { type, strategy, authority, profile, definition, incarnationCross, centers[9], channels[], gates[26] }. Entrada de quiz apenas do tipo: POST /human-design/type. Compatibilidade de duas pessoas: POST /human-design/connection com { personA, personB } (cada um { date, time, timezone }).
• Previsão: POST /forecast/transits (aspectos de trânsito-para-natal ocidental, ingresso, estações retrógradas) e POST /forecast/timeline (fusão entre domínios de trânsitos ocidentais, limites de dasha védico e dias críticos de biorritmo) ambos recebem { birthData: { date, time, timezone }, startDate?, endDate? } — horizonte máximo de 90 dias, eventos classificados por significance. Mapa astral anual de aniversário: POST /forecast/solar-return com { date, time, year, latitude, longitude, timezone } (precisa de coordenadas, então chame Localização primeiro).
• I Ching tiragem: GET /iching/cast (aleatório) ou POST /iching/daily/cast (tiragem diária com semente). Resposta é { hexagram, lines, changingLinePositions, resultingHexagram } onde cada hexagram tem { number (1-64), symbol, chinese, english, pinyin, judgment, image, interpretation, changingLines }. Detalhe do hexagrama: GET /iching/hexagrams/{number} onde number é inteiro 1..64.
• Biorritmo diário: POST /biorhythm/daily com { birthDate, date?, seed? }. Previsão (janela de 30-90 dias): POST /biorhythm/forecast com { birthDate, startDate?, endDate? }. Compatibilidade: POST /biorhythm/compatibility com { person1: { birthDate }, person2: { birthDate }, targetDate? } — birthDate plano por pessoa, sem hora ou coordenadas.
• Cristais: GET /crystals/zodiac/{sign} (correspondência zodiacal), GET /crystals/chakra/{chakra} (chakra é insensível a maiúsculas/minúsculas e separado por espaço: Root, Sacral, Solar Plexus codificado em URL Solar%20Plexus, Heart, Throat, Third Eye codificado em URL Third%20Eye, Crown — kebab third-eye falha na validação), GET /crystals/birthstone/{month} (mês inteiro 1..12), GET /crystals/search?q= para texto livre.
• Consulta do número dos anjos: GET /angel-numbers/lookup?number=1111. Funciona para QUALQUER inteiro positivo (fallback de raiz digital).
• Símbolo de sonho: GET /dreams/symbols/{slug} (slug em kebab-case, ex. flying, water, snake, falling, house

… [truncado para tradução]