playbooks

home / skills / openclaw / skills / iex-cloud

iex-cloud skill

/skills/oscraters/iex-cloud

This skill enables secure, token-authenticated access to IEX Cloud REST data and provides a scriptable CLI for reliable market calls.

npx playbooks add skill openclaw/skills --skill iex-cloud

Review the files below or copy the command above to add this skill to your agents.

Files (8)
SKILL.md
3.7 KB
---
name: iex-cloud
description: Use this skill when a task needs IEX Cloud market data through the REST API (quotes, charts, fundamentals, market lists, and batch calls), including secure token handling and scriptable CLI usage.
homepage: https://github.com/oscraters/iex-cloud-skill
metadata: {"openclaw":{"skillKey":"iex-cloud","homepage":"https://github.com/oscraters/iex-cloud-skill","sourceRepository":"https://github.com/oscraters/iex-cloud-skill.git","requires":{"env":["IEX_TOKEN"],"optionalEnv":["IEX_CLOUD_TOKEN","IEX_BASE_URL"],"primaryEnv":["IEX_TOKEN"],"bins":["curl"],"optionalBins":["jq"]}}}
---

# IEX Cloud

## Overview

This skill provides an operational workflow for IEX Cloud API usage in OpenClaw tasks:
- selecting the right endpoint for market-data requests
- building valid authenticated requests
- handling API and transport errors
- running repeatable calls through a local Bash CLI

## Quick Start

1. Preferred for OpenClaw: store the token at `skills.entries.iex-cloud.apiKey` and back it with a SecretRef via `openclaw secrets configure`.
2. For direct shell use outside OpenClaw, set `export IEX_TOKEN=...`.
3. Compatibility fallback: `export IEX_CLOUD_TOKEN=...`.
4. Read endpoint/parameter guidance in `references/api_docs.md`.
5. Use `scripts/iex_cloud_cli.sh` for reliable calls.

Example:

```bash
scripts/iex_cloud_cli.sh quote AAPL
scripts/iex_cloud_cli.sh chart AAPL 1m
scripts/iex_cloud_cli.sh movers mostactive
```

## Workflow

1. Classify request type:
- latest quote: `quote`
- historical bars: `chart`
- company/fundamentals: `company`, `stats`
- market movers: `movers`
- multi-symbol pulls: `batch`
2. Validate required parameters before call dispatch.
3. Execute request with token auth and timeout.
4. Validate response class:
- HTTP failure / transport failure
- JSON payload containing API error fields
- empty or malformed payload
5. Normalize output downstream as needed.

## Authentication and Safety

- Primary token env var: `IEX_TOKEN`.
- Compatibility token alias: `IEX_CLOUD_TOKEN`.
- In OpenClaw, prefer `skills.entries.iex-cloud.apiKey` with SecretRefs over plaintext config.
- Do not hardcode tokens in source files.
- Do not print full token values in logs.
- Prefer query parameter `token=...` when using these endpoints.
- The CLI accepts only trusted IEX API hosts for base URL overrides and warns when a non-default trusted override is used.
- `raw` calls are limited to relative IEX API paths. Do not pass full URLs.

## Reliability Guidance

- Use bounded timeouts (`curl --max-time` in CLI).
- Handle non-2xx responses as hard failures.
- Validate symbol, range, and list-type inputs early.
- For large jobs, use batch endpoints where possible.
- If you modify `IEX_BASE_URL` or pass `--base-url`, expect a warning so the change is visible during review.

## OpenClaw Secrets Management

- OpenClaw can inject this skill's API key from `skills.entries.iex-cloud.apiKey` for each agent run.
- Secret refs are preferred over plaintext because the resolved secret wins at runtime and plaintext is ignored.
- Recommended operator flow:
  - `openclaw secrets audit --check`
  - `openclaw secrets configure`
  - `openclaw secrets audit --check`
- For direct shell usage outside OpenClaw, export `IEX_TOKEN` in your shell instead.

## Included Files

- `scripts/iex_cloud_cli.sh`: Bash CLI for common endpoints and raw calls.
- `scripts/README.md`: CLI usage examples and command reference.
- `references/api_docs.md`: operational endpoint reference and guardrails.

## Resources

- API docs: https://iexcloud.io/docs/api/
- Status page: https://status.iexapis.com/
- Base URL (stable): `https://cloud.iexapis.com/stable`
- Sandbox URL: `https://sandbox.iexapis.com/stable`
- OpenClaw secrets: https://docs.openclaw.ai/gateway/secrets

Overview

This skill provides a safe, scriptable workflow for calling the IEX Cloud REST API to retrieve quotes, charts, fundamentals, market lists, and batch data. It includes token handling patterns suitable for OpenClaw and direct shell use, a small CLI for repeatable calls, and guidance for error handling and normalization.

How this skill works

It classifies requests (quote, chart, company, stats, movers, batch), validates inputs, constructs authenticated HTTP calls using a configured token, and applies bounded timeouts. The included Bash CLI wraps curl with trusted base-url checks and helpers for common endpoints; responses are checked for HTTP and API-level errors and returned as normalized JSON payloads for downstream processing.

When to use it

  • Fetching real-time or delayed market quotes for a symbol or list of symbols.
  • Retrieving historical bar data (charts) for visualization or backtesting.
  • Pulling company fundamentals, statistics, or other reference data.
  • Running market movers and list queries (most active, gainers, losers).
  • Batching large symbol sets to reduce HTTP overhead and stay within rate limits.

Best practices

  • Store the API token in skills.entries.iex-cloud.apiKey with a SecretRef in OpenClaw rather than embedding it in code.
  • For local shell use, export IEX_TOKEN (fallback IEX_CLOUD_TOKEN) and avoid printing full token values in logs.
  • Validate symbol, range, and list-type inputs before making requests to avoid wasted API calls.
  • Use batch endpoints for large pulls and bounded timeouts (curl --max-time) to avoid hanging jobs.
  • Accept only trusted IEX base URLs and surface warnings if a non-default base URL is supplied.

Example use cases

  • scripts/iex_cloud_cli.sh quote AAPL to fetch a fast market quote for AAPL.
  • scripts/iex_cloud_cli.sh chart AAPL 1m to pull 1-month historical bars for charting.
  • scripts/iex_cloud_cli.sh movers mostactive to list today’s most active tickers for a scanner.
  • Batch request to retrieve quotes for a portfolio of symbols in one call to reduce rate use.
  • Use OpenClaw secrets injection to run periodic aggregation jobs without exposing tokens in configs.

FAQ

How should I store the API token for automated OpenClaw runs?

Put the token at skills.entries.iex-cloud.apiKey and configure a SecretRef using openclaw secrets configure; the secret override will be used at runtime.

Can I override the IEX base URL for testing?

Yes—sandbox and custom trusted hosts are supported, but the CLI warns on non-default trusted overrides and raw calls are restricted to relative IEX paths.

What happens on non-2xx or malformed responses?

Treat non-2xx HTTP responses as hard failures, detect API error fields in JSON, and validate payload structure before normalization.