# Authentication and verification
Source: https://docs.askgina.ai/agents/authentication
Connect with OAuth or explicitly scoped manual tokens.
![Gina Agent Setup showing token permissions, Read-only — view data selected, no active tokens, and an MCP configuration with a placeholder token.]()
## Connect with OAuth
Use OAuth when your [client](/connect/index) supports it. Add the selected server URL, choose the client's connect or authenticate action, and complete Gina sign-in and consent in the browser. Return to the client and refresh its tools.
The read endpoint requests `tools:read`; execution endpoints request `tools:execute`. OAuth authentication and installing skills are separate steps.
## Use a manual token
For a client that accepts a Bearer token:
1. Sign in to [Gina Agent Setup](https://askgina.ai/agent-setup), also available as **Agent Setup** in the app sidebar.
2. Under **Generate Token**, enter a descriptive **Token name**, such as your client and device.
3. Set **Access level** to **Read-only — view data** for research. The form can default to **Full access — view and execute**; explicitly change it before continuing.
4. Choose **Generate Token** and copy the generated configuration into the client's private MCP settings. Never commit the token or paste it into a chat.
5. For execution, deliberately choose full access and retain only the required venue connection from the generated configuration.
6. Refresh the client and run [the first-request test](/start/first-request).
Tokens expire after 90 days. Use **Active Tokens → Revoke** in Agent Setup to revoke a token. Generate a replacement when needed and update the client's private settings.
![Gina Agent Setup showing the wallet-access notice, Full access — view and execute selected, and a venue-specific MCP configuration with a placeholder token.]()
## Verify the right connection
| Check | Expected for read-only |
| - | - |
| URL | `https://askgina.ai/ai/gina/mcp` |
| Scope | `tools:read` |
| Tools | Named market and account reads; no `bash` or execution tools |
| First result | A successful Gina research response, not a generic model answer |
A token with the wrong scope will not become valid by changing the URL. Reconnect through OAuth or generate a correctly scoped token. For errors, see [connection troubleshooting](/help/connections).
# Plugins and skills
Source: https://docs.askgina.ai/agents/plugins-and-skills
Understand the research plugin and its four canonical skills.
The Ask Gina plugin bundles a read-only MCP connection with four research skills. A **connection** makes tools available; a **skill** tells the agent when and how to use them. Authentication is still required.
## Choose a research skill
| Skill | Use it for | Example |
| - | - | - |
| `review-gina-account` | Linked wallets, cross-chain holdings, scheduled prompts and runs | “Show my linked wallets.” |
| `research-spot-tokens` | Spot prices, token metadata, charts, completed swap history | “Chart ETH over the past week.” |
| `research-hyperliquid` | Hyperliquid and HIP-3 markets, positions, orders, fills | “Show my Hyperliquid positions.” |
| `research-prediction-markets` | Polymarket discovery, order books, positions | “Which prediction markets expire soon?” |
These skills cannot place trades, transfer assets, change leverage, redeem positions, or create/edit schedules. Adding another MCP server does not change that boundary.
## Install for your host
Follow [your host's setup page](/connect/index). A host-specific plugin can include extra features, such as Cursor slash commands; direct MCP connections provide tools without automatically installing skills.
The canonical skill sources are in [askgina/plugins](https://github.com/askgina/plugins/tree/main/plugins/ask-gina/skills). Each skill has a `SKILL.md` under `plugins/ask-gina/skills//`. Use those sources rather than copying older skill bodies from documentation.
For hosts with manual skill loading, install only the desired skill directories into the host's documented skill location, then start a new session. The repository's contributor instructions and build internals are not user skills.
## OpenClaw and other clients
OpenClaw is one client, not a separate Gina skill family. Follow [OpenClaw setup](/connect/openclaw) for the connection and skill-loading route. Legacy ClawHub commands are not the installation source for these four research skills.
## Package availability
Source code and host adapters do not establish marketplace approval. Check [your client's setup guide](/connect/index#choose-your-client) for its direct connection route and marketplace availability. Do not assume SDK/CLI source can be installed from a public package registry.
# Start here if you're an agent
Source: https://docs.askgina.ai/agents/start
A complete bootstrap sequence for using Gina tools and skills.
Use this page to connect Gina and complete the user's task. Read the steps in order; follow linked host instructions rather than guessing configuration syntax.
## 1. Identify the host and intent
Identify whether you are running in ChatGPT, Claude, Codex, Cursor, OpenClaw, or another MCP client. Find your [client's setup guide](/connect/index#choose-your-client).
For research or account visibility, choose Gina Read. If the user wants execution, choose the relevant [write connection](/write-access/index). Do not infer permission to execute from an installation request.
## 2. Install or connect
Follow the host's guide. Use its supported plugin route when available; otherwise configure direct MCP. Installing a skill alone does not connect tools. Do not invent package names, marketplace listings, or executable install scripts.
The [plugin and skill guide](/agents/plugins-and-skills) identifies canonical skill paths and verified source installation routes. SDK and CLI source in the repository do not imply published packages.
## 3. Load the applicable skill
For the read-only plugin, select the skill matching the task: account review, spot research, Hyperliquid research, or prediction-market research. Follow its routing and error handling. These skills remain read-only even if other connections are installed.
## 4. Authenticate
Start the host's connection flow and let the user complete Gina OAuth in the browser. For a token-based client, direct the user to [manual authentication](/agents/authentication). Keep credentials in the host's private configuration, never in chat, committed files, or reports.
If a user action is required, state exactly what they need to do and resume verification afterward.
## 5. Discover and verify tools
Refresh or list the connection's tools. For Gina Read, expect named research tools such as `getSimplePrice`, `getTokenChart`, and `getAccountAddresses`, possibly with a host prefix. There must be no `bash` or mutation tool from this connection.
If the boundary differs, check the configured URL and scope before continuing. For write connections, compare discovery with the venue reference and inspect current schemas before constructing calls.
## 6. Run a read-only smoke test
Follow [First successful request](/start/first-request). Verify that Gina returned the requested asset and time range. Report missing data or authentication failures rather than substituting model memory.
## 7. Complete the user's task
Use the tool result as evidence. Preserve timestamps, units, market identity, and missing-data information. A read-only skill cannot fulfill a write request; route the user to the selected execution interface without claiming that the research connection can execute.
For execution, follow the venue's documented authorization and result-verification behavior. Do not report a submitted or pending transaction as settled.
## Documentation versus operational tools
The [documentation index](https://docs.askgina.ai/llms.txt) helps you find instructions. Follow its Markdown links for full text. It is not an account connection and cannot trade or inspect a user's wallet. Gina's operational MCP URLs are listed in [Choose your access](/mcp-access/index).
# ChatGPT
Source: https://docs.askgina.ai/connect/chatgpt
Add a custom read-only Gina connection in ChatGPT.
Use a custom MCP connection when developer mode is available for your account. Your workspace administrator may need to enable it. This guide does not assume a published Ask Gina marketplace listing.
## Add Gina
1. In ChatGPT, open **Settings → Security and login → Developer mode** and enable developer mode if available.
2. Open **Plugins**, choose the plus button, and enter **Ask Gina** as the name.
3. Under **Connection**, enter `https://askgina.ai/ai/gina/mcp` and use OAuth authentication.
4. Create the connection, complete Gina authentication, and review its discovered tools.
5. Enable the connection in your conversation.
Gina Read requests `tools:read`. Do not add an execution URL as a substitute for the read-only connection. ChatGPT may render structured results; a text result is sufficient to verify tools work.
The host's current instructions are in [Connect from ChatGPT](https://developers.openai.com/plugins/deploy/connect-chatgpt). If developer mode is unavailable, use another [supported client](/connect/index).
## Verify your first result
Ask **“Use Gina to show ETH in USD over the past seven days.”** Confirm a Gina tool ran and the response identifies ETH and the requested period. Follow [First successful request](/start/first-request) for the expected tool boundary and recovery steps.
This connection is read-only. For trading or transfers, see [Write access (Degen mode)](/write-access/index). A direct connection does not automatically install [research skills](/agents/plugins-and-skills).
![A Gina request in ChatGPT returning a Gold up-or-down prediction-market widget with a price chart and recent session outcomes.]()
*Prediction-market result in ChatGPT, captured September 7, 2026. This example shows a September 3 market and a host CSP off badge; it illustrates the widget, not current market status or required connection settings.*
# Claude
Source: https://docs.askgina.ai/connect/claude
Add Gina in one tap on the web, iPhone or Android. You can also connect it by hand in Claude Desktop or Claude Code.
## Add Gina in one tap
Pick where you use Claude. Each button opens Claude's **Add custom connector** screen with Gina filled in.
**Web** opens claude.ai and also adds Gina to Claude Desktop. **iPhone** and **Android** open the Claude app, so tap them on your phone.
Confirm to add Gina, then sign in to Gina when Claude asks. The phone buttons use app links Claude does not document, so they can change. If a button does not open the add screen, use the steps below.
## Claude web and Desktop
Use a remote connector, rather than a local stdio server configuration:
1. Open **Customize → Connectors → + → Add custom connector**.
2. Enter **Ask Gina** and `https://askgina.ai/ai/gina/mcp`.
3. Add the connector, choose **Connect**, and complete Gina OAuth.
4. Enable Gina in the conversation's connectors or tools controls.
![Claude Customize screen with Connectors selected and Gina listed under Your custom connectors, showing askgina.ai and a green checkmark.]()
*Gina added as a custom connector in Claude, captured September 7, 2026.*
For Team or Enterprise, an owner may need to add the connector first. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
## Claude on iPhone and Android
Gina added on the web or in Desktop also appears in the Claude phone apps signed in to the same account. Turn it on in a chat with **+ → Connectors**. To add it from your phone instead, use the iPhone or Android button at the top of this page.
## Claude Code: direct MCP
Run:
```sh theme={null}
claude mcp add --transport http ask-gina https://askgina.ai/ai/gina/mcp
```
Start Claude Code, open `/mcp`, select Ask Gina, and complete browser authentication. See [Claude Code MCP](https://code.claude.com/docs/en/mcp).
## Claude Code: repository plugin
To install the research skills together with their MCP configuration, use the repository-hosted marketplace:
```text theme={null}
/plugin marketplace add askgina/plugins
/plugin install ask-gina@ask-gina-plugins
```
Restart the session if prompted, then use `/mcp` to authenticate the included connection. Choose this route instead of adding a duplicate direct connection. The repository marketplace is distinct from a listing in Anthropic's public directory.
## Verify your first result
Ask **“Use Gina to show ETH in USD over the past seven days.”** Confirm a Gina tool ran and the response identifies ETH and the requested period. Follow [First successful request](/start/first-request) for the expected tool boundary and recovery steps.
This connection is read-only. For trading or transfers, see [Write access (Degen mode)](/write-access/index). A direct connection does not automatically install [research skills](/agents/plugins-and-skills).
![A successful Gina request in Claude showing the user's HYPE chart prompt, the Gina tool call, a HYPE/USD chart, and Claude's summary.]()
*Example of a successful chart request in Claude, captured September 7, 2026. This HYPE example uses a different asset and period from the verification prompt above; displayed prices are historical.*
# Codex
Source: https://docs.askgina.ai/connect/codex
Connect Gina through Codex MCP settings and OAuth.
Add the remote server using the Codex CLI:
```sh theme={null}
codex mcp add ask-gina --url https://askgina.ai/ai/gina/mcp
codex mcp login ask-gina
```
The login command opens the OAuth flow. Complete it in the browser, then start or refresh your Codex session.
Alternatively, merge this entry into your Codex MCP configuration:
```toml theme={null}
[mcp_servers.ask-gina]
url = "https://askgina.ai/ai/gina/mcp"
```
Use the login command after configuring the server. Do not overwrite your other MCP settings. See [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
## Add research skills
The direct connection provides tools. To add the [four research skills](/agents/plugins-and-skills), copy their complete directories from `plugins/ask-gina/skills/` in [the source repository](https://github.com/askgina/plugins/tree/main/plugins/ask-gina/skills) into your project's `.agents/skills/` directory. Start a new session and confirm Codex lists them. Do not replace existing unrelated skills.
No public package installation or marketplace approval is implied by this source route.
## Verify your first result
Ask **“Use Gina to show ETH in USD over the past seven days.”** Confirm a Gina tool ran and the response identifies ETH and the requested period. Follow [First successful request](/start/first-request) for the expected tool boundary and recovery steps.
This connection is read-only. For trading or transfers, see [Write access (Degen mode)](/write-access/index). A direct connection does not automatically install [research skills](/agents/plugins-and-skills).
# Grok Bot
Source: https://docs.askgina.ai/connect/grok-bot
Add Gina as a plugin and use its research tools in Grok Bot.
## Add Gina
Grok Bot displays connectors as plugins. When Ask Gina is available in your marketplace:
1. Open **Settings → Plugins → Marketplace**.
2. Find **Ask Gina** and choose **Add**.
3. Complete Gina authentication in your browser if requested.
4. In chat, type **@** and attach Gina to the task.
See [Grok Bot's connection guide](https://docs.x.ai/grok-bot/computer-and-apps#connect-an-app) and [plugin settings](https://docs.x.ai/grok-bot/settings-and-notifications#plugins).
The Gina package targets the Cursor marketplace route used by Grok Bot. A live Ask Gina listing has not been verified here. If it is unavailable, use another [supported client](/connect/index). Cursor's local plugin installation and Grok web's custom connector are separate setup routes, documented under [Others](/connect/other-clients).
## Verify your first result
Ask **“Use Gina to show ETH in USD over the past seven days.”** Confirm a Gina tool ran and the response identifies ETH and the requested period. Follow [First successful request](/start/first-request) if tools are missing or authentication fails.
Use [read-only access](/mcp-access/index) for research. Trading and transfers require separate [Write access (Degen mode)](/write-access/index). Installing a plugin alone does not verify its connection or permissions.
![Gina Predictoor in Grok Bot displaying a prediction-market research table with market links, sides, odds, liquidity, times, and qualitative assessments.]()
*Gina prediction research in Grok Bot, supplied by the product owner on September 7, 2026. The displayed report is dated August 30, 2026; prices and assessments are historical output.*
# Hermes Agent
Source: https://docs.askgina.ai/connect/hermes
Connect Hermes Agent to Gina's read-only MCP tools.
## Connect MCP
Merge this server entry into `~/.hermes/config.yaml`:
```yaml theme={null}
mcp_servers:
ask-gina:
url: https://askgina.ai/ai/gina/mcp
auth: oauth
```
Authenticate from a fresh terminal:
```sh theme={null}
hermes mcp login ask-gina
hermes chat
```
Complete Gina sign-in in your browser. Hermes discovers the server's tools when it connects. See [Hermes MCP documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp/) for remote-host authentication and version-specific configuration.
For manual Bearer authentication, follow [Gina Agent Setup](/agents/authentication) and the host's `headers` configuration. Keep tokens in private client settings.
## Verify your first result
Ask **“Use Gina to show ETH in USD over the past seven days.”** Confirm a Gina tool ran and the response identifies ETH and the requested period. Follow [First successful request](/start/first-request) for troubleshooting.
This configuration is read-only. Trading and transfers require separate [Write access (Degen mode)](/write-access/index). MCP setup does not install [Gina research skills](/agents/plugins-and-skills). Authenticated Gina testing and rich-result rendering in Hermes remain unverified.
# Get Started
Source: https://docs.askgina.ai/connect/index
Connect your agent to Gina to monitor your portfolio or trade across supported markets.
## Choose your client
Select your agent above to open its setup guide, or see [Perplexity](/connect/perplexity) and [other clients](/connect/other-clients). The client guides start with read-only access. Choose what you want your agent to do below to find the right connection.
## What do you want to do?
### Monitor your onchain portfolio
Use the **read-only Ask Gina plugin** to review linked wallets, holdings across chains, and market positions. Your agent can research prices and inspect your portfolio without placing trades or moving funds. The plugin combines the Gina Read MCP connection with research skills.
[Explore the read-only plugin](/agents/plugins-and-skills).
### Have your agent trade crypto across chains
Use **Spot MCP** to research tokens, prepare swaps and transfers, and execute transactions on supported chains. Connect this when you want your agent to act on your instructions, from swapping an asset to sending tokens.
[Explore Spot MCP](/spot-mcp/index).
### Have your agent trade on prediction markets
Use **Predictions MCP** to discover Polymarket markets, inspect odds and order books, and buy or sell outcome shares. Your agent can also track positions and manage orders through the same connection.
[Explore Predictions MCP](/predictions-mcp/index).
### Have your agent trade perpetual futures
Use **Perps MCP** to research Hyperliquid and HIP-3 markets, place orders, and manage perpetual-futures positions. Your agent can inspect margin and funding, adjust leverage, and set stop-loss or take-profit orders.
[Explore Perps MCP](/perps-mcp/index).
Spot, Predictions, and Perps use separate [write connections (Degen mode)](/write-access/index). Connect the markets you want your agent to trade; the read-only plugin does not grant execution access.
Next: [First successful request](/start/first-request).
# OpenClaw
Source: https://docs.askgina.ai/connect/openclaw
Connect native MCP and load Gina research skills separately.
OpenClaw is one way to run Gina tools and skills. The current research bundle comes from [askgina/plugins](https://github.com/askgina/plugins), not the older venue-specific skill bodies previously published in these docs.
## Connect MCP
In an OpenClaw version with native MCP support:
1. Open **Settings → MCP → Add server**.
2. Name the server `ask-gina`, choose **Streamable HTTP**, and enter `https://askgina.ai/ai/gina/mcp`.
3. Configure OAuth in the server's scoped settings and save the server.
4. Authenticate and probe the connection:
```sh theme={null}
openclaw mcp login ask-gina
openclaw mcp doctor ask-gina --probe
```
Follow [OpenClaw's MCP guide](https://docs.openclaw.ai/tools/mcp) for version-specific settings. If your client uses Bearer authentication, generate a read-only token using [Gina Agent Setup](/agents/authentication) and store it in the client's private server configuration. Do not paste a token into a skill file.
## Load the research skills
Clone the source repository and copy the desired complete directories from `plugins/ask-gina/skills/` into your workspace `.agents/skills/`. Alternatively, configure `skills.load.extraDirs` with the absolute path to the checked-out Gina skills directory. Start a new session and confirm the selected skills are available.
See [OpenClaw skill loading](https://docs.openclaw.ai/tools/skills) and [Gina's skill catalog](/agents/plugins-and-skills). Skills and MCP authentication are separate: verify both.
Legacy ClawHub venue skills may use execution endpoints. They are not interchangeable with the current four read-only research skills. For execution, follow the venue's current guide rather than an old copied skill body.
## Verify your first result
Ask **“Use Gina to show ETH in USD over the past seven days.”** Confirm a Gina tool ran and the response identifies ETH and the requested period. Follow [First successful request](/start/first-request) for the expected tool boundary and recovery steps.
This connection is read-only. For trading or transfers, see [Write access (Degen mode)](/write-access/index). A direct connection does not automatically install [research skills](/agents/plugins-and-skills).
# Others
Source: https://docs.askgina.ai/connect/other-clients
Configure Streamable HTTP and verify Gina tool discovery.
Your client needs remote **Streamable HTTP** MCP support and either OAuth or a configurable Bearer header. Follow its own configuration schema; MCP settings are not identical across hosts.
## Configure a research connection
Use these connection values:
| Setting | Value |
| - | - |
| Name | `ask-gina` |
| Transport | Streamable HTTP |
| URL | `https://askgina.ai/ai/gina/mcp` |
| OAuth scope | `tools:read` |
Prefer the client's OAuth flow. For a manual Bearer header, follow [authentication](/agents/authentication); use a correctly scoped token and private configuration. A client that only supports local stdio servers cannot connect directly with these values.
## Plugin or skill support
If the client supports skills, use [the canonical research skill directories](/agents/plugins-and-skills). If it only supports tools, you can still complete the first request without installing skills. Rich charts and slash commands depend on the host.
## Cursor: direct MCP
Merge this into your project `.cursor/mcp.json` or user `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"ask-gina": {
"url": "https://askgina.ai/ai/gina/mcp"
}
}
}
```
Open Cursor's MCP settings and connect Ask Gina. Complete Gina OAuth in the browser, then enable its tools. This URL-only configuration lets Cursor negotiate Streamable HTTP and OAuth. See [Cursor MCP](https://prod.cursor.com/docs/mcp).
## Cursor: local source plugin
For skills and slash commands, clone [askgina/plugins](https://github.com/askgina/plugins) and copy the complete `plugins/ask-gina` directory to `~/.cursor/plugins/local/ask-gina`. Use a real directory, not an external symlink. Preserve any existing installation rather than overwriting it blindly.
Reload Cursor and connect the plugin's Gina MCP server. The plugin provides four research skills and the commands `/review-gina-account`, `/research-spot-tokens`, `/research-hyperliquid`, and `/research-prediction-markets`. Avoid enabling a duplicate direct MCP connection.
## Grok web
At [Grok connectors](https://grok.com/connectors), choose **New Connector → Custom**, enter `https://askgina.ai/ai/gina/mcp`, and complete authentication. Availability depends on the host. See [Grok's connector guide](https://docs.x.ai/grok/connectors).
## Verify your first result
Ask **“Use Gina to show ETH in USD over the past seven days.”** Confirm a Gina tool ran and the response identifies ETH and the requested period. Follow [First successful request](/start/first-request) for the expected tool boundary and recovery steps.
This connection is read-only. For trading or transfers, see [Write access (Degen mode)](/write-access/index). A direct connection does not automatically install [research skills](/agents/plugins-and-skills).
# Perplexity
Source: https://docs.askgina.ai/connect/perplexity
Configure a custom remote MCP connector with OAuth.
Use Perplexity's custom **remote** connector when enabled for your account or workspace. You do not need a local MCP bridge for this route.
1. Open account **Settings → Connectors → + Custom connector**.
2. Choose **Remote**.
3. Enter **Ask Gina** and `https://askgina.ai/ai/gina/mcp`.
4. Select **OAuth** as the authentication method and add the connector.
5. Open its connector card, authenticate with Gina, and enable it for your query.
See [Perplexity's remote connector guide](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors). If your account lacks this option, check workspace policy or use another [client](/connect/index).
The host configuration route is documented; an authenticated Gina test and Gina-specific result widgets in Perplexity have not been verified here. Use the actual tool response to check success.
## Verify your first result
Ask **“Use Gina to show ETH in USD over the past seven days.”** Confirm a Gina tool ran and the response identifies ETH and the requested period. Follow [First successful request](/start/first-request) for the expected tool boundary and recovery steps.
This connection is read-only. For trading or transfers, see [Write access (Degen mode)](/write-access/index). A direct connection does not automatically install [research skills](/agents/plugins-and-skills).
# Financial evaluations
Source: https://docs.askgina.ai/evaluations
Explore how models perform on financial tasks using Gina's read-only tools.
We have run financial evaluations across multiple models on tasks spanning spot markets, perpetual futures, and prediction markets. Each attempt is graded against task-specific checks for tool use and task completion. The results are published on [Gina Evals](https://evals.askgina.ai/).
## What we evaluate
The tasks test whether a model selects the required tools, supplies the required arguments, follows the task's restrictions, and completes without errors. Some tasks need a single tool call; others require several calls in a particular order. Each attempt starts a fresh conversation with access to read-only financial tools.
## Explore the results
* [Model leaderboard](https://evals.askgina.ai/): compare pass rates across task categories, with timing and estimated cost where available.
* [Tasks and grading criteria](https://evals.askgina.ai/#/tasks): inspect the prompts and checks used to grade each attempt.
* [Evaluation methodology](https://evals.askgina.ai/#/methodology): see how runs are conducted, scores are calculated, and missing data is handled.
The published scores measure tool use and task completion; final-answer accuracy and trading returns are not scored. Models used different clients, and the samples are small, so read the methodology and run details alongside the results.
To try Gina with your own assistant, visit [Get Started](/connect/index).
# Connection troubleshooting
Source: https://docs.askgina.ai/help/connections
Recover from missing tools, authentication errors, and unexpected access.
| Problem | What to check | Next action |
| - | - | - |
| No Gina tools | Connection enabled, correct URL, completed authentication | Refresh tools or start a new session |
| Sign-in keeps returning | Client supports remote MCP and OAuth; callback accepted | Remove the failed connection and follow the host's current setup guide |
| Unauthorized or wrong scope | Read endpoint needs `tools:read`; execution needs `tools:execute` | Reconnect or generate a token with the matching access level |
| Read connection shows execution | Configured server and any separately enabled connections | Check each connection's URL and tool list before using it |
| Expired manual token | Expiry under Agent Setup → Active Tokens | Generate a replacement and update private client settings |
| Generic answer without tool use | Gina enabled for this chat; prompt selected a supported task | Ask explicitly to use Gina and inspect tool activity |
| Tool failed or data missing | Error message, requested asset, account, time range | Correct the input; retry once for an explicit transient failure |
| Missing chart or widget | Host's supported result rendering | Use the text result; a widget is not required for a successful call |
Do not repeatedly retry a transaction because its result is unclear. Follow the venue's status-verification instructions first.
See [authentication](/agents/authentication), [host setup](/connect/index), or venue-specific help for [Spot](/spot-mcp/troubleshooting), [Predictions](/predictions-mcp/troubleshooting), and [Perps](/perps-mcp/troubleshooting).
If you contact [Gina support](https://askgina.ai/support), include the client, server URL, time, and a redacted error. Do not include tokens, private keys, or recovery phrases.
# Gina Read
Source: https://docs.askgina.ai/mcp-access/gina-read
Safe-mode research across Spot, Predictions, and Perps
Gina Read is the read-only MCP connection for cross-market research and account visibility.
## Server URL
```
https://askgina.ai/ai/gina/mcp
```
It requests `tools:read` and lists named tools for Spot prices and charts, Hyperliquid state, prediction markets, cross-chain holdings, linked addresses, and scheduled-prompt visibility.
No `bash` tool
No swap, transfer, trade, funding, or scheduling mutations
One connection for reads across all three markets
## Connect and try it
Follow [your client setup](/connect/index), then run [First successful request](/start/first-request). For task examples, start with [account review](/read-only/account), [spot research](/read-only/spot), [prediction markets](/read-only/predictions), or [perps](/read-only/perps).
## When You Need to Write
Add only the venue-specific server you need:
* [Spot MCP](/spot-mcp) for swaps, transfers, LP operations, transaction execution, and Spot scheduling
* [Predictions MCP](/predictions-mcp) for Polymarket execution
* [Perps MCP](/perps-mcp) for Hyperliquid and HIP-3 execution
Existing execute-scoped Gina credentials cannot be used on Gina Read. Reconnect through OAuth to receive a read-scoped token.
## Read tool reference
These are the canonical catalog names. Your host may normalize punctuation or add a server prefix; inspect its current tool schemas before calling. No tool in this catalog grants execution.
| Tool | Family |
| - | - |
| `gina.getCrosschainPortfolio` | portfolio |
| `gina.getAccountAddresses` | portfolio |
| `gina.listScheduledPrompts` | portfolio |
| `spot.getTokenMetadata` | spot |
| `spot.getTokenChart` | spot |
| `spot.getSimplePrice` | spot |
| `spot.fetchSwapHistory` | spot |
| `perps.getHyperliquidAccount` | perps |
| `perps.getHyperliquidPositions` | perps |
| `perps.getHyperliquidOpenOrders` | perps |
| `perps.getHyperliquidPortfolio` | perps |
| `perps.getHyperliquidMarkets` | perps |
| `perps.getHyperliquidPrice` | perps |
| `perps.getHyperliquidPrices` | perps |
| `perps.getHyperliquidAssetData` | perps |
| `perps.getHyperliquidPerpDexes` | perps |
| `perps.fetchHyperliquidTrades` | perps |
| `perps.fetchHyperliquidCandles` | perps |
| `perps.fetchHyperliquidOrderBook` | perps |
| `perps.previewHyperliquidOrderCost` | perps |
| `perps.createHyperliquidTable` | perps |
| `perps.executeSqlQuery` | perps |
| `predictions.searchPredictionMarkets` | predictions |
| `predictions.getExpiringMarkets` | predictions |
| `predictions.getPredictionOrderbook` | predictions |
| `predictions.getSeriesMarket` | predictions |
| `predictions.getPredictionMarketDetails` | predictions |
| `predictions.fetchPolymarketData` | predictions |
| `predictions.fetchPolymarketHistory` | predictions |
| `predictions.getPolymarketPositions` | predictions |
| `predictions.getPolymarketOrderHistory` | predictions |
# Choose your access
Source: https://docs.askgina.ai/mcp-access/index
Compare read-only research with venue-specific trading and transfers.
Choose permissions before connecting a client. One read-only connection covers all markets; execution is split into three venue-specific connections.
| Access | Server URL | OAuth scope | Purpose |
| - | - | - | - |
| Read-only | `https://askgina.ai/ai/gina/mcp` | `tools:read` | Research and account visibility across markets |
| Write access (Degen mode) | `https://askgina.ai/ai/spot/mcp` | `tools:execute` | Spot execution, swaps, transfers, LP operations, and scheduling |
| Write access (Degen mode) | `https://askgina.ai/ai/predictions/mcp` | `tools:execute` | Prediction-market execution |
| Write access (Degen mode) | `https://askgina.ai/ai/perps/mcp` | `tools:execute` | Perpetual-futures execution |
## Read-only access
Choose [Gina Read](/mcp-access/gina-read) for prices, market discovery, positions, linked addresses, holdings, and schedule visibility. It exposes named research tools. It cannot trade, transfer, change leverage, or create schedules.
The [Ask Gina plugin and research skills](/agents/plugins-and-skills) use this connection. Installing the plugin does not grant execution access.
## Write access (Degen mode)
Choose [write access](/write-access/index) for an agent that should act on your behalf. Connect only the venue you need. Spot exposes native tools plus `bash`; Predictions and Perps expose `bash` with their own allowed host tools. See each venue's reference for the exact tool boundary.
Write access can place orders or move funds. A request to prepare or quote differs from a request to execute; follow the selected venue's workflow.
## Match the app's labels
In [Agent Setup](https://askgina.ai/agent-setup), **Read-only — view data** corresponds to Gina Read. **Full access — view and execute** corresponds to write access (Degen mode).
The token form can start with full access selected. For research, explicitly select **Read-only — view data** before generating a token. An existing execute-scoped credential is not a read credential: reconnect or generate a token with the correct scope.
Next: [choose your client](/connect/index), or [start here if you're an agent](/agents/start).
# Perps client setup
Source: https://docs.askgina.ai/perps-mcp/client-setup
Connect perps execution tools using the right host configuration.
This is **write access (Degen mode)**. It requests `tools:execute` and can perform perps actions. For research only, use [Gina Read](/mcp-access/gina-read).
## Claude Code
```sh theme={null}
claude mcp add --transport http perps https://askgina.ai/ai/perps/mcp
```
Open `/mcp` in Claude Code and complete OAuth. See [Claude setup](/connect/claude) for the host's authentication flow.
## Codex
```sh theme={null}
codex mcp add perps --url https://askgina.ai/ai/perps/mcp
codex mcp login perps
```
Alternatively, merge this into your Codex configuration, then run the login command:
```toml theme={null}
[mcp_servers.perps]
url = "https://askgina.ai/ai/perps/mcp"
```
## Cursor
Merge the entry into `.cursor/mcp.json` or `~/.cursor/mcp.json`, preserving other servers:
```json theme={null}
{
"mcpServers": {
"perps": {
"url": "https://askgina.ai/ai/perps/mcp"
}
}
}
```
Connect and complete Gina OAuth from Cursor's MCP settings.
## Other clients and manual tokens
Use a [Streamable HTTP client](/connect/other-clients) with this venue URL. Check the host's support for execution tools before connecting. For Bearer-token clients, follow [authentication](/agents/authentication) and deliberately choose **Full access — view and execute**; keep only the required venue entry.
The credential must be valid for this venue and carry `tools:execute`. A read-only token or an old Gina execute grant is not a substitute. Complete a fresh connection if the grant is rejected.
Next: run the [read-only connection checks](/perps-mcp/quick-start) before attempting execution.
# FAQ
Source: https://docs.askgina.ai/perps-mcp/faq
Frequently asked questions about Gina Perps MCP
Perps MCP is an MCP server by Gina for Hyperliquid perpetual futures. It lets MCP clients use a sandboxed `bash` tool to inspect market data, manage positions, place orders, work with HIP-3 DEXes, and analyze fetched data.
Any client that supports MCP over streamable HTTP:
* **Claude Code** via `claude mcp add`
* **Codex** via native `codex mcp add` and OAuth
* **Cursor** via Settings -> MCP or `.cursor/mcp.json`
* **Windsurf** via Settings -> MCP
* **OpenCode** via `opencode mcp add`
* Any client supporting generic JSON MCP config
No. Perps MCP is default enabled for authenticated Gina users. You still need to sign in through
MCP OAuth or provide a token bound to the Perps MCP resource.
That's the OAuth sign-in flow. Sign in to Gina and approve access for your MCP client, then return
to your client and retry `tools/list`.
* Fetch Hyperliquid prices, markets, candles, trades, and order books - View account state,
positions, open orders, and portfolio details - Place, modify, and cancel perps orders - Adjust
leverage and isolated margin - Discover HIP-3 DEXes and work with provider-scoped markets - Move
funds into or out of supported Hyperliquid/HIP-3 flows
The MCP tool runs inside a sandboxed workspace, but perps trading is financially risky. Start with
read-only commands, check schemas before execution, and review order size, side, leverage, asset,
and provider context before trading.
Start with [Troubleshooting](/perps-mcp/troubleshooting). If you're still stuck, reach out on [Twitter/X](https://x.com/askginadotai).
# Features Table
Source: https://docs.askgina.ai/perps-mcp/features
Complete reference of Perps MCP capabilities with example prompts and commands
Complete reference of Perps MCP capabilities. You can prompt naturally, or ask your client to call `bash` with the direct command shown.
Start with `host-tools --brief` and `host-tools schema ` before using an unfamiliar trading or funding tool.
| Feature | What It Does | Example Prompts | Direct Command |
| - | - | - | - |
| **Account State** | View account, margin, positions, open orders, and portfolio | `"show my perps positions"` `"what open orders do I have?"` | `host-tools getHyperliquidPositions` |
| **Account Health** | Snapshot authenticated account exposure and margin | `"check my perps account health"` | `host-tools perps.accountHealth includeExitEstimates=true` |
| **Markets** | List canonical Hyperliquid markets and asset metadata | `"show Hyperliquid markets"` `"what is BTC funding?"` | `host-tools getHyperliquidMarkets` |
| **Market Radar** | Rank markets by activity and compare retained samples | `"radar for active perp markets"` | `host-tools perps.marketRadar limit=10` |
| **Prices** | Fetch one or many live perps prices | `"BTC perps price"` `"price BTC ETH SOL"` | `host-tools getHyperliquidPrice '{\"asset\":\"BTC\"}'` |
| **HIP-3 Discovery** | Search HIP-3 markets and list builder-deployed DEXes | `"search HIP-3 markets for CL"` `"list HIP-3 DEXes"` | `host-tools perps.hip3.search query=CL` |
| **HIP-3 Prices** | Read venue-scoped HIP-3 prices | `"price CL on xyz"` | `host-tools perps.hip3.price '{\"dex\":\"xyz\",\"coin\":\"CL\"}'` |
| **Orders** | Place market or limit orders | `"place a BTC limit order"` `"open a small ETH short"` | `host-tools placeHyperliquidOrder '{\"asset\":\"BTC\",\"isBuy\":true,\"size\":0.01,\"orderType\":\"market\"}'` |
| **Stops** | Place stop-loss or take-profit style trigger orders | `"set a BTC stop loss"` | `host-tools placeHyperliquidStopOrder '{\"asset\":\"BTC\",\"triggerPrice\":95000,\"size\":0.01,\"isBuy\":false}'` |
| **Order Management** | Cancel or modify open orders | `"cancel my open ETH order"` `"modify that limit order"` | `host-tools cancelHyperliquidOrder ''` |
| **Leverage & Margin** | Adjust leverage and isolated margin | `"set BTC leverage to 5x"` `"add isolated margin"` | `host-tools adjustHyperliquidLeverage '{\"asset\":\"BTC\",\"leverage\":5}'` |
| **Funding** | Deposit or withdraw Hyperliquid USDC | `"deposit to Hyperliquid"` `"withdraw from Hyperliquid"` | `host-tools depositToHyperliquid ''` |
| **HIP-3 Funds** | Move collateral into or out of a selected HIP-3 DEX | `"fund xyz HIP-3 with 100 USDC"` | `host-tools perps.hip3.fund '{\"providerContext\":{\"providerId\":\"hip3:xyz\"},\"amount\":\"100\"}'` |
| **Data Fetching** | Fetch trades, candles, and order books into sandbox tables | `"fetch BTC candles into SQL"` | `host-tools fetchHyperliquidCandles '{\"coin\":\"BTC\",\"interval\":\"1h\"}'` |
| **SQL Analysis** | Query fetched perps data with DuckDB/SQLite-style workflows | `"query large BTC trades"` | `sql query "SELECT * FROM LIMIT 10"` |
Account health and market radar require a separately authorized [Perps MCP
connection](/perps-mcp/client-setup) with `tools:execute`. They are not read tools in the Ask Gina
listed plugin.
## Account health
`perps.accountHealth` requires an authenticated account. It defaults to canonical Hyperliquid. Pass `providerContext` with `{"providerId":"hip3:xyz"}` for an enabled HIP-3 venue.
The response includes at most 64 positions. Set `includeExitEstimates=true` for indicative exit estimates on at most eight positions, not fill guarantees. The tool does not assign a health score or calculate historical performance.
## Market radar
`perps.marketRadar` accepts `limit` from 1 to 50, defaulting to 10, and an optional `dex`, such as `dex=xyz`. Omit `dex` for canonical Hyperliquid.
Eligible markets rank by descending 24-hour traded volume, then open interest, then absolute 24-hour price change, with coin name breaking ties. This measures activity and exposure, not liquidity, depth, or executable size. Excluded-market details are capped at 100.
Rank, volume, open-interest, and mark-price deltas compare with a shared sample for that venue, not the caller's previous request. Samples rotate no more often than every five minutes and expire after seven days. Rows without a prior entry are marked `firstSeen`.
Radar returns the complete JSON response inline or in an artifact. It does not automatically extract the rows into SQL tables.
## Discovery Flow
Use this sequence when you are unsure which tool to call:
```json theme={null}
{ "command": "capabilities --json" }
```
```json theme={null}
{ "command": "host-tools --brief" }
```
```json theme={null}
{ "command": "host-tools schema getHyperliquidPrice" }
```
## HIP-3 Provider Context
For HIP-3 tools, prefer provider context over legacy venue-only inputs:
```json theme={null}
{
"providerContext": {
"providerId": "hip3:xyz"
}
}
```
This keeps pricing, orders, margin, funding, and SQL analysis scoped to the selected HIP-3 provider.
# Perps MCP
Source: https://docs.askgina.ai/perps-mcp/index
Connect to Gina's Perps MCP server and work with Hyperliquid perpetual futures from any MCP client
Gina's Perps MCP server lets you analyze markets, inspect account state, manage positions, and trade Hyperliquid perpetual futures from your AI coding assistant or MCP client.
For Ask Gina's broader user-facing capabilities, including wallets, market research, Recipes, Memory, networks, fees, and safety boundaries, see the [Product Guide](/product-guide).
## What You Can Do
Use natural language in your client, or call the sandbox `bash` tool directly.
*"BTC perps price"* *"show Hyperliquid markets"* *"search HIP-3 markets for CL"*
*"show my perps positions"* *"what open orders do I have?"* *"summarize my margin status"*
*"place a BTC limit order"* *"set a stop loss"* *"cancel my open ETH order"*
*"list HIP-3 DEXes"* *"show XYZ markets"* *"price CL on xyz"*
*"deposit to Hyperliquid"* *"fund the xyz HIP-3 DEX"* *"return HIP-3 funds"*
*"fetch BTC candles"* *"load order book depth into SQL"* *"query large trades"*
Full breakdown of market data, account state, trading, HIP-3, funding, and SQL workflows.
## Server URL
```
https://askgina.ai/ai/perps/mcp
```
Perps MCP is available by default to authenticated Gina users. There is no separate perps MCP feature flag to enable.
## Get Started
Connect and run your first price lookup
Config for Claude Code, Codex, Cursor, and more
## Quick Success Check
Add `https://askgina.ai/ai/perps/mcp` to your MCP client and restart it.
Your client triggers OAuth. Sign in to Gina in the browser and approve access.
Ask your AI assistant to use the `bash` tool:
```json theme={null}
{ "command": "echo ok" }
```
You should see `ok` in the output.
## Safety
Perpetual futures use leverage and can liquidate quickly. Start with read-only commands such as
prices, positions, and schemas before placing orders or moving funds.
## Advanced: MCP Resources
If your client supports MCP prompts and resources, you'll also see:
| Type | URI |
| - | - |
| Prompt | `perps_guide` |
| Resource | `mcp://perps/guide` |
| Resource | `mcp://perps/connect` |
| Resource | `mcp://perps/quickstart` |
| Resource | `mcp://perps/policy` |
| Resource | `mcp://perps/filesystem` |
| Resource | `mcp://perps/commands/index` |
| Resource | `mcp://perps/host-tools/index` |
| Resource | `mcp://perps/prompts/perps_guide` |
# Introduction
Source: https://docs.askgina.ai/perps-mcp/introduction
What Perps MCP is and when to use it
Perps MCP is Gina's dedicated MCP server for Hyperliquid perpetual futures. It exposes a sandboxed `bash` tool that can discover and call allowlisted perps host tools for market data, account state, trading, HIP-3 DEX workflows, funding, and SQL analysis.
## How It Works
Your MCP client connects to:
```
https://askgina.ai/ai/perps/mcp
```
After OAuth sign-in, the client receives one MCP tool: `bash`. Inside that sandbox, use commands such as `capabilities`, `host-tools`, `sql`, and `ts-exec` to inspect the tool surface and run perps workflows.
Search canonical Hyperliquid and HIP-3 markets, inspect prices, funding, open interest, and
order books.
Place, modify, and cancel orders; set stops; adjust leverage and isolated margin.
Fetch trades, candles, and order books into the sandbox, then query them with SQL.
## Default Access
Perps MCP is default enabled for authenticated Gina users. Runtime access is controlled by MCP authentication, not by a perps-specific feature flag.
## Get Started
Connect and run a first verification flow.
See the full feature reference with example prompts and direct commands.
# Quick Start
Source: https://docs.askgina.ai/perps-mcp/quick-start
Connect to Gina's Perps MCP and run your first Hyperliquid lookup
Get connected and run your first perps market query.
## 1. Add the Server
Follow [Perps client setup](/perps-mcp/client-setup) to add the server and authenticate. Use the configuration for your host.
## 2. Connect & Sign In
After adding the server, restart your MCP client or reload the window.
Your client will trigger the OAuth flow. Sign in to Gina and approve access.
Once authenticated, `bash` will appear alongside your client's built-in tools. Try asking your
AI assistant: *"What tools do you have from the perps server?"*
## 3. Run First Checks
Call `bash` with:
```json theme={null}
{ "command": "echo ok" }
```
You should see `ok` in the output.
Then inspect the sandbox and host tools:
```json theme={null}
{ "command": "capabilities --json" }
```
```json theme={null}
{ "command": "host-tools --brief" }
```
## 4. Get a Perps Price
Run a live Hyperliquid price lookup:
```json theme={null}
{ "command": "host-tools getHyperliquidPrice '{\"asset\":\"BTC\"}'" }
```
You should see JSON output with current BTC perpetual futures price data.
## Next Steps
* [What You Can Do](/perps-mcp/features) - full features with example prompts
* [Client Setup](/perps-mcp/client-setup) - detailed config for every client
* [Troubleshooting](/perps-mcp/troubleshooting) - smoke test and common fixes
# Troubleshooting
Source: https://docs.askgina.ai/perps-mcp/troubleshooting
Verify your connection and fix common issues with Gina Perps MCP
## Smoke Test
### Prerequisites
Your MCP client is installed and running
You've added `https://askgina.ai/ai/perps/mcp` as a server
You can open a browser for OAuth sign-in
### Run These Commands
```json theme={null}
{ "command": "echo ok" }
```
Expected: `ok`
```json theme={null}
{ "command": "commands --help host-tools" }
```
Expected: help text describing host-tools usage
```json theme={null}
{ "command": "host-tools --name getHyperliquidPrice --limit 5 --full" }
```
Expected: JSON output including `getHyperliquidPrice` tool details
```json theme={null}
{ "command": "host-tools getHyperliquidPrice '{\"asset\":\"BTC\"}'" }
```
Expected: JSON output with live BTC perps price data
## Common Issues
### 1. Check the Server URL
Make sure your MCP client is using this exact URL:
```
https://askgina.ai/ai/perps/mcp
```
### 2. Sign-In Not Working
Your client should trigger OAuth automatically. If not:
* **Claude Code:** run `/mcp` and pick `perps`
* **Codex:** run `codex mcp login perps`
* **Cursor:** go to Settings -> MCP and check status
Sign in to Gina in the browser window that opens.
Return to your MCP client. `bash` should appear as an available tool.
### 3. Signed In But No Tools
If you signed in but no `bash` tool appears, remove the `perps` server from your client, re-add it with the URL above, restart the client, and authenticate again.
### 4. Host Tool Input Fails
Check the schema before retrying:
```json theme={null}
{ "command": "host-tools schema getHyperliquidPrice" }
```
Most failures are malformed JSON, an asset symbol mismatch, or missing HIP-3 `providerContext` for
provider-scoped tools.
### 5. Trading or Funding Is Not What You Intended
Stop and inspect state before continuing:
```json theme={null}
{ "command": "host-tools getHyperliquidPositions" }
```
```json theme={null}
{ "command": "host-tools getHyperliquidOpenOrders" }
```
Perps MCP is default enabled for authenticated users, but financial actions still use the underlying tool confirmations and risk checks.
## Still Stuck?
Check the [FAQ](/perps-mcp/faq) or reach out on [Twitter/X](https://x.com/askginadotai).
# Predictions client setup
Source: https://docs.askgina.ai/predictions-mcp/client-setup
Connect predictions execution tools using the right host configuration.
This is **write access (Degen mode)**. It requests `tools:execute` and can perform predictions actions. For research only, use [Gina Read](/mcp-access/gina-read).
## Claude Code
```sh theme={null}
claude mcp add --transport http predictions https://askgina.ai/ai/predictions/mcp
```
Open `/mcp` in Claude Code and complete OAuth. See [Claude setup](/connect/claude) for the host's authentication flow.
## Codex
```sh theme={null}
codex mcp add predictions --url https://askgina.ai/ai/predictions/mcp
codex mcp login predictions
```
Alternatively, merge this into your Codex configuration, then run the login command:
```toml theme={null}
[mcp_servers.predictions]
url = "https://askgina.ai/ai/predictions/mcp"
```
## Cursor
Merge the entry into `.cursor/mcp.json` or `~/.cursor/mcp.json`, preserving other servers:
```json theme={null}
{
"mcpServers": {
"predictions": {
"url": "https://askgina.ai/ai/predictions/mcp"
}
}
}
```
Connect and complete Gina OAuth from Cursor's MCP settings.
## Other clients and manual tokens
Use a [Streamable HTTP client](/connect/other-clients) with this venue URL. Check the host's support for execution tools before connecting. For Bearer-token clients, follow [authentication](/agents/authentication) and deliberately choose **Full access — view and execute**; keep only the required venue entry.
The credential must be valid for this venue and carry `tools:execute`. A read-only token or an old Gina execute grant is not a substitute. Complete a fresh connection if the grant is rejected.
Next: run the [read-only connection checks](/predictions-mcp/quick-start) before attempting execution.
# FAQ
Source: https://docs.askgina.ai/predictions-mcp/faq
Frequently asked questions about Gina Predictions MCP
Predictions MCP is an MCP server by Gina that lets you search, analyze, and trade on prediction markets (Polymarket) directly from any MCP-compatible client like Cursor, Claude Code, Codex, or Windsurf.
Any client that supports MCP over streamable HTTP: - **Claude Code** — via `claude mcp add` -
**Codex** — via native `codex mcp add` and OAuth - **Cursor** — via Settings → MCP or
`.cursor/mcp.json` - **Windsurf** — via Settings → MCP - **OpenCode** — via `opencode mcp add` -
Any client supporting the generic JSON MCP config format
That's the OAuth sign-in flow. You need to sign in to Gina and approve access for your MCP client.
This only happens once per session. After signing in, return to your client and retry
`tools/list`.
No. Authentication happens automatically through OAuth in your browser. Your MCP client handles
the token exchange.
* Search prediction markets (sports, politics, crypto, entertainment) - Get trending/popular
markets - View market details, odds, and volume - Execute trades on Polymarket - Track your open
positions and P\&L
Yes. The `bash` tool runs in a sandboxed workspace: - Read-only commands (search, list, trending)
have no side effects - Trading actions require explicit confirmation for large orders - You can
start with read-only operations and only opt into trading when ready
Every user gets a quota of free AI credits to start experimenting. Once you get to advanced usage,
you can use the crypto in your Gina wallet to top up credits.
Start with [Troubleshooting](/predictions-mcp/troubleshooting). If you're still stuck, reach out on [Twitter/X](https://x.com/askginadotai).
# Features Table
Source: https://docs.askgina.ai/predictions-mcp/features
Complete reference of Predictions MCP capabilities with example prompts
Complete reference of Predictions MCP capabilities with example prompts.
These are natural language prompts — just type them into your AI assistant after connecting. No
special syntax needed.
| Feature | What It Does | Example Prompts |
| - | - | - |
| **Market Search** | Find markets by topic, sport, or keyword | `"NBA markets tomorrow"` `"Trump election odds"` |
| **Trending** | See what's popular right now | `"what's trending on Polymarket?"` `"what are people betting on?"` |
| **Crypto Prices** | Recurring price prediction markets | `"BTC 15 minute up or down"` `"ETH hourly prediction"` |
| **Stocks & Indices** | Stock and index prediction markets | `"AAPL daily up or down"` `"S&P 500 daily"` |
| **Expiring Markets** | Markets about to resolve | `"markets ending in 2 hours"` `"NBA games ending tonight"` |
| **Trading** | Buy/sell outcome shares | `"bet $10 on eagles to win"` `"buy $50 of Yes"` |
| **Limit Orders** | Place orders at specific prices | `"buy Yes at 0.40 or better"` `"avoid slippage"` |
| **Positions** | View your current holdings & P\&L | `"show my Polymarket positions"` `"what's my P&L?"` |
| **Performance** | Win rate, volume, trade history | `"what's my win rate?"` `"show my trade history"` |
| **Order Management** | View/cancel pending orders | `"show my open orders"` `"cancel all pending orders"` |
| **Redeem Winnings** | Claim resolved winning positions | `"redeem my winnings"` `"what can I redeem?"` |
| **Data Analysis** | SQL queries on market data | `"fetch crypto markets into SQL"` `"run a query"` |
| **Automations** | Scheduled recurring tasks | `"daily market briefing at 9am"` `"alert me on swings"` |
# Data & Automations
Source: https://docs.askgina.ai/predictions-mcp/features-advanced
SQL analysis on market data and scheduled automations
## Data Analysis
Fetch market data into a local SQLite database and run custom queries.
### Fetch & Analyze
```
"fetch the top 50 crypto prediction markets into a table"
"load my Polymarket trading history into SQL"
"pull all sports markets ending this week"
```
### SQL Queries
After fetching data, run analysis:
```
"query: SELECT slug, yes_price FROM markets WHERE category = 'crypto' ORDER BY volume DESC LIMIT 10"
"show me markets where the odds changed more than 10% in the last 24 hours"
"find the highest volume markets ending today"
```
***
## Automations & Recipes
Set up recurring scheduled tasks that run automatically.
```
"create a daily briefing of trending prediction markets every morning at 9am"
"alert me when any NBA market has odds swing more than 15%"
"schedule a weekly portfolio performance summary"
"set up a recurring check for new crypto price markets"
```
### Manage Automations
```
"show my scheduled automations"
"pause my morning briefing recipe"
"delete the NBA alert automation"
```
# Discovery
Source: https://docs.askgina.ai/predictions-mcp/features-discovery
Search markets, find trending picks, crypto price bets, and expiring markets
## Searching Markets
Find prediction markets on any topic. Gina searches Polymarket's full catalogue.
### By Topic
```
"show me NBA markets"
"Trump election odds"
"Bitcoin prediction markets"
"Super Bowl winner odds"
"Fed rate decision markets"
"Oscar best picture predictions"
```
### By Date
```
"NBA games tomorrow"
"markets ending today"
"what's resolving this week"
"crypto markets expiring in the next 2 hours"
"sports predictions for this weekend"
```
### Trending & Popular
```
"what's trending on Polymarket?"
"show me the most popular markets right now"
"what are people betting on?"
"high volume prediction markets"
```
### Multi-Outcome Events
```
"who will win the Premier League?"
"World Cup 2026 odds"
"which team wins the NBA championship?"
```
***
## Crypto Price Predictions
Polymarket has recurring crypto price markets with different timeframes. Ask about any supported asset.
### Quick Price Bets
```
"will BTC go up in the next 15 minutes?"
"ETH hourly up or down"
"SOL 4 hour prediction"
"daily Bitcoin market"
"weekly Ethereum prediction"
```
### Supported Assets & Timeframes
| Asset | 15 Min | Hourly | 4 Hour | Daily | Weekly |
| - | - | - | - | - | - |
| BTC | ✅ | ✅ | ✅ | ✅ | ✅ |
| ETH | ✅ | ✅ | ✅ | ✅ | ✅ |
| SOL | ✅ | ✅ | ✅ | ✅ | ✅ |
| XRP | ✅ | ✅ | ✅ | ✅ | ✅ |
| DOGE | ✅ | ✅ | ✅ | ✅ | ✅ |
### Stock & Index Markets
```
"AAPL daily up or down"
"Netflix weekly multi-strikes"
"S&P 500 daily prediction"
"Gold daily up or down"
```
***
## Finding Expiring Markets
Discover markets that are about to resolve — great for finding last-minute opportunities.
### By Time Window
```
"markets ending in the next hour"
"what's expiring in 4 hours?"
"sports markets ending tonight"
"markets resolving tomorrow"
```
### By Category
```
"NBA games ending today"
"crypto markets expiring soon"
"political markets resolving this week"
"entertainment markets ending today"
```
# Portfolio & Balances
Source: https://docs.askgina.ai/predictions-mcp/features-portfolio
Track positions, performance, manage orders, and redeem winnings
## View Positions
```
"what are my Polymarket positions?"
"show my prediction market holdings"
"how are my predictions doing?"
"what's my current P&L?"
```
***
## Trading History & Performance
```
"show my Polymarket trading history"
"what's my win rate?"
"how much have I traded on Polymarket?"
"show my prediction market performance"
```
***
## Order Management
View and manage your open limit orders.
```
"show my open Polymarket orders"
"what limit orders do I have pending?"
"cancel my order on the Bitcoin market"
"cancel all my pending orders"
```
***
## Redeeming Winnings
When a market resolves and you won, redeem your shares for \$1 each.
```
"redeem my Polymarket winnings"
"claim my winning positions"
"what positions can I redeem?"
"do I have any resolved markets to claim?"
```
# Trading
Source: https://docs.askgina.ai/predictions-mcp/features-trading
Place trades, limit orders, and understand prediction market outcomes
## Placing Trades
Execute real trades on Polymarket. Buy or sell outcome shares.
Trading uses real money (USDC on Polygon). Always review trade details before confirming.
### By Dollar Amount
```
"bet $5 on eagles to win tonight"
"put $20 on cowboys to win this weekend"
"bet $10 on trump winning the election"
"buy $50 of Yes on the Bitcoin market"
```
### By Shares
```
"buy 100 shares of YES in the bitcoin market"
"buy 50 NO shares for the fed rate decision"
"sell 25 shares of my Lakers position"
```
### Limit Orders
```
"buy Yes at 0.40 or better on the Trump market"
"place a limit order for No at 0.25"
"buy Yes shares but avoid slippage"
```
***
## Understanding Outcomes
* **Yes price of \$0.70** = 70% implied probability of happening
* **No price** is always (1 − Yes price)
* Winning shares pay out **\$1.00 each**
* Your profit = \$1.00 − purchase price per share
### Example
If you buy 100 Yes shares at \$0.40 each:
* **Cost:** \$40
* **If Yes wins:** you get $100 → **$60 profit\*\*
* **If No wins:** shares worth $0 → **$40 loss\*\*
# Predictions MCP
Source: https://docs.askgina.ai/predictions-mcp/index
Connect to Gina's Predictions MCP server and trade on prediction markets from any MCP client
Gina's Predictions MCP server lets you search, analyze, and trade on prediction markets directly from your AI coding assistant or MCP client.
For Ask Gina's broader user-facing capabilities, including wallets, market research, Recipes, Memory, networks, fees, and safety boundaries, see the [Product Guide](/product-guide).
## What You Can Do
Just type natural language prompts — no special syntax needed.
*"NBA markets tomorrow"* *"Trump election odds"* *"what's trending?"*
*"BTC 15 min up or down"* *"ETH hourly prediction"* *"AAPL daily market"*
*"bet \$5 on eagles to win"* *"buy 100 YES shares"* *"limit order at 0.40"*
*"show my positions"* *"what's my P\&L?"* *"what's my win rate?"*
*"markets ending in 2 hours"* *"NBA games ending tonight"*
*"daily market briefing at 9am"* *"alert me on odds swings"*
Full breakdown of everything you can do: search, trade, analyze, automate — with copy-paste
prompts for each.
## Server URL
```
https://askgina.ai/ai/predictions/mcp
```
## Get Started
Connect in under 2 minutes
Config for Claude Code, Codex, Cursor, and more
## Quick Success Check
Add `https://askgina.ai/ai/predictions/mcp` to your MCP client and restart it.
Your client triggers OAuth — sign in to Gina in the browser and approve access.
Ask your AI assistant to use the `bash` tool:
```json theme={null}
{ "command": "echo ok" }
```
You should see `ok` in the output.
## Safety
`bash` runs inside a sandboxed workspace. Start with read-only commands (search, list) before
executing trades. Large trade orders require explicit confirmation.
## Advanced: MCP Resources
If your client supports MCP prompts and resources, you'll also see:
| Type | URI |
| - | - |
| Prompt | `predictions_guide` |
| Resource | `mcp://predictions/guide` |
| Resource | `mcp://predictions/connect` |
| Resource | `mcp://predictions/quickstart` |
| Resource | `mcp://predictions/policy` |
| Resource | `mcp://predictions/filesystem` |
| Resource | `mcp://predictions/commands/index` |
| Resource | `mcp://predictions/host-tools/index` |
# Predictions MCP
Source: https://docs.askgina.ai/predictions-mcp/introduction
Connect an MCP client to Ask Gina's Polymarket discovery, trading, and portfolio tools
Predictions MCP connects supported Model Context Protocol clients to Ask Gina's Polymarket tools. Use natural-language prompts to discover markets, inspect market details and pricing, prepare trades, and review prediction-market positions through your connected client.
For Ask Gina's broader user-facing capabilities, including wallets, market research, Recipes, Memory, networks, fees, and safety boundaries, see the [Product Guide](/product-guide).
## How It Works
The server exposes one MCP tool, `bash`. Your client invokes it from your prompt; inside that sandbox, `host-tools` commands provide prediction-market discovery, pricing, trading, and portfolio operations.
Search Polymarket and inspect markets, outcomes, pricing, liquidity, and related details.
Prepare and execute supported prediction-market trades through the authenticated MCP connection.
Review prediction-market positions, orders, activity, and portfolio information.
## MCP Capabilities
| Capability | Predictions MCP |
| - | - |
| **Prediction-market discovery** | ✅ |
| **Market details and pricing** | ✅ |
| **Prediction-market trading** | ✅ |
| **Orders and positions** | ✅ |
| **Prediction-market portfolio review** | ✅ |
| **Advanced prediction workflows** | ✅ |
## Get Started
Connect your MCP client and start using Predictions MCP.
Explore the Predictions MCP feature reference and example prompts.
# Quick Start
Source: https://docs.askgina.ai/predictions-mcp/quick-start
Connect to Gina's Predictions MCP in under 2 minutes
Get connected and run your first prediction market query in under 2 minutes.
## 1. Add the Server
Follow [Predictions client setup](/predictions-mcp/client-setup) to add the server and authenticate. Use the configuration for your host.
## 2. Connect & Sign In
After adding the server, restart your MCP client (or reload the window in Cursor).
Your client will trigger the OAuth flow — a browser window opens. Sign in to Gina and approve access.
In **Claude Code**, run `/mcp` to see server status and trigger auth. In **Cursor**, go to Settings → MCP to check the connection.
Once authenticated, `bash` will appear alongside your client's built-in tools. Try asking your AI assistant: *"What tools do you have from the predictions server?"*
## 3. Run Your First Command
Call `bash` with:
```json theme={null}
{ "command": "echo ok" }
```
You should see `ok` in the output. You're connected! 🎉
## 4. Search a Market
Now try a real prediction market search:
```json theme={null}
{ "command": "host-tools searchPredictionMarkets '{\"query\":\"NBA\"}'" }
```
You should see JSON output with live market data.
## Troubleshooting
Some clients show a sign-in link instead of opening a browser automatically. Look in your client UI for an auth link, or see [Client Setup](/predictions-mcp/client-setup) for manual sign-in commands.
Remove the server from your client, re-add it, and run `tools/list` again.
Start with a simple command (`echo ok`) first. If that works, try:
```json theme={null}
{ "command": "commands --help host-tools" }
```
## Next Steps
* [What You Can Do](/predictions-mcp/features) — full features with example prompts
* [Client Setup](/predictions-mcp/client-setup) — detailed config for every client
* [Troubleshooting](/predictions-mcp/troubleshooting) — smoke test and common fixes
# Troubleshooting
Source: https://docs.askgina.ai/predictions-mcp/troubleshooting
Verify your connection and fix common issues with Gina Predictions MCP
## Smoke Test
A quick checklist to verify everything is working.
### Prerequisites
Your MCP client is installed and running
You've added `https://askgina.ai/ai/predictions/mcp` as a server
You can open a browser for OAuth sign-in
### Run These Commands
```json theme={null}
{ "command": "echo ok" }
```
Expected: `ok`
```json theme={null}
{ "command": "commands --help host-tools" }
```
Expected: help text describing host-tools usage
```json theme={null}
{ "command": "host-tools --name searchPredictionMarkets --limit 5 --full" }
```
Expected: JSON output including `searchPredictionMarkets` tool details
```json theme={null}
{ "command": "host-tools searchPredictionMarkets '{\"query\":\"NBA\"}'" }
```
Expected: JSON output with live market data
All checks pass? You're fully connected!
***
## Common Issues
### 1. Check the Server URL
Make sure your MCP client is using this exact URL:
```
https://askgina.ai/ai/predictions/mcp
```
If the URL is different (even slightly), remove the server and add it again with the correct URL.
### 2. Sign-In Not Working
Your client should trigger OAuth automatically. If not: - **Claude Code:** run `/mcp` and pick
`predictions` - **Codex:** run `codex mcp login predictions` - **Cursor:** go to Settings → MCP
and check status
Sign in to Gina in the browser window that opens.
Click "Approve" when prompted.
Return to your MCP client — `bash` should now appear as an available tool.
### 3. No Browser Window Opens
Some MCP clients show a sign-in link or "Authorize" button instead of opening a browser automatically.
* Look in your client UI for an auth link and follow it
* Try these client-specific commands:
Start `claude`, then run `/mcp` and pick `predictions`.
`bash codex mcp login predictions `
Restart Cursor, then open any chat and ask to use the predictions tool. The OAuth flow should
trigger.
`bash opencode mcp auth predictions `
### 4. Signed In But No Tools
If you signed in but no `bash` tool appears:
Remove `predictions` from your MCP client.
Add the server again with URL `https://askgina.ai/ai/predictions/mcp`.
Restart your client and complete the sign-in flow again.
### 5. Commands Fail
First, verify the basics work:
```json theme={null}
{ "command": "echo ok" }
```
If that succeeds, check what's available:
```json theme={null}
{ "command": "commands --help host-tools" }
```
If a specific command fails, check that your input JSON is valid. A common issue is missing or
mismatched quotes in the JSON argument.
### 6. Connection Timeout
* Check your internet connection
* Try a different network (VPN or corporate firewalls can block MCP connections)
* Ensure the server URL uses `https://` (not `http://`)
## Still Stuck?
Check the [FAQ](/predictions-mcp/faq) or reach out on [Twitter/X](https://x.com/askginadotai).
# Copy trading
Source: https://docs.askgina.ai/product-guide/automations/copy-trading
Explore a trader, review the proposed setup, and monitor execution.
# Copy trading
Copy trading uses another trader's activity as an input to automated trading. It involves execution and funds, so it is separate from following a trader for research. The interface is available only to accounts with copy trading enabled.
## Review a trader and start setup
1. Open **Copy trading** in the sidebar. If the entry is unavailable, your account does not currently expose this interface.
2. Open a trader to review their profile, activity, and performance over the selected period.
3. Choose **Copy trade** to begin setup for that trader.
4. Review the proposed venue, funding, sizing, limits, and execution instructions presented during setup. Resolve missing requirements before enabling the workflow.
5. After activation, inspect the resulting runs and your own positions. A trader's activity does not prove that your account executed the same trade.
Available controls depend on the venue and setup. Do not assume the displayed historical return is the return your account will receive: timing, available funds, prices, fees, and execution failures can differ.
For account visibility without copying, use [read-only account review](/read-only/account). For reviewing actual activity, see [transactions and portfolio](/product-guide/transactions-and-portfolio).
# Create and test a recipe
Source: https://docs.askgina.ai/product-guide/automations/recipes
Turn a task into a reusable workflow and inspect its first result.
# Create and test a recipe
A recipe describes work Gina can repeat. Start with a research task so you can inspect a useful result without executing a trade. Creation availability depends on your account.
1. Choose **Create** in the sidebar.
2. Enter **“Summarize BTC and ETH market changes with sources. Include the time range and do not trade.”**
3. Review the generated workflow and its inputs. Check that its steps match the request.
4. Keep **Simulated mode** enabled and choose **Run**.
5. Read the step statuses and final output. Confirm both assets, the time range, and sources appear; correct failed or unexpected steps before continuing.
Simulated runs can use live data while simulating side effects. **Run Live** can perform real actions. Review a recipe again after changing its instructions or inputs.
When the result meets your needs, [add a schedule](/product-guide/automations/schedules). If the recipe needs saved research, name the file in [account Memory](/product-guide/memory).
# Schedule and monitor a recipe
Source: https://docs.askgina.ai/product-guide/automations/schedules
Choose a cadence, confirm its timezone, and inspect completed runs.
# Schedule and monitor a recipe
First [create and test a recipe](/product-guide/automations/recipes). Scheduling availability depends on your account.
1. Choose **Schedule** on the workflow.
2. Select a suggested cadence or enter a custom one, such as **“Weekdays at 9 AM Europe/London.”**
3. Check the timezone and intended frequency.
4. Use **Schedule workflow now** or **Apply custom cadence**, as shown by the panel.
5. Review the resulting schedule, then open **Automations** to find the configured work and its runs.
Inspect a run's steps, output, and final status. A queued or accepted run has not necessarily completed. For a market report, verify that the result covers the expected assets and reporting period.
If a run fails, read its error and check the inputs, account access, and available credits. Correct the recipe and test it again. Scheduled work can run late or fail because of provider availability, limits, or timeouts.
# Webhook-triggered recipes
Source: https://docs.askgina.ai/product-guide/automations/webhooks
Understand event-triggered work and inspect why a recipe ran.
# Webhook-triggered recipes
A webhook lets a supported integration trigger a recipe when an event occurs. A schedule runs by time; a webhook runs in response to an event. Availability and configuration depend on the recipe and provider.
## Configure the supported trigger
Use the trigger configuration supplied by the recipe or integration. Follow its required event type, authentication or signature requirements, and payload format. There is no universal Gina webhook payload or generic setup screen for every provider.
Test the recipe before enabling event-triggered execution. Keep webhook credentials and usable trigger URLs private; do not put secrets into a prompt or a screenshot.
## Inspect an event-triggered run
1. Open the resulting run or conversation.
2. Find **Webhook Trigger**. Review the provider, event type, received time, and displayed event fields.
3. Use **Copy JSON** if you need the trigger details for your own debugging. Review and redact the contents before sharing them.
4. Choose **Ask assistant about this trigger** when available to have Gina explain why the run fired.
5. Inspect the recipe's steps and final output separately. Receiving a webhook does not prove the task completed.
If the expected run is missing, check the provider's delivery result and the configured event and payload. If a run exists but failed, inspect that run's error before retrying, especially when the workflow can execute transactions.
# Ask Gina Product Guide
Source: https://docs.askgina.ai/product-guide/index
Open Gina, ask a research question, and find your next task.
# Ask Gina Product Guide
Open [Gina](https://askgina.ai) in your browser to research markets, inspect your wallet, and run supported transactions or automations. No MCP installation is needed for the web app.
## First chat
1. Choose **Log In** or **Launch Gina** and sign in.
2. Choose **Chat** in the sidebar.
3. Ask **“Show ETH's price in USD over the past seven days.”**
4. Check the asset, time range, and source in the result. No deposit is needed.
5. Use **Chats** to return to earlier conversations.
## Next steps
* [Liquidity positions and Yield](/product-guide/liquidity-positions): LP balances, fees and exits.
* [Wallet](/product-guide/wallet-and-account): addresses and balances.
* [Transactions](/product-guide/transactions-and-portfolio): holdings, proposals, and execution.
* [Research](/product-guide/market-research), [Predictions](/product-guide/predictions), and [Perps](/product-guide/perps): markets and positions.
* [Automations](/product-guide/recipes-and-webhooks): create, test, and schedule work.
* [Files and memory](/product-guide/memory): reusable research.
* [Agent Setup](/agents/authentication): connect external assistants.
A request to **send** or **swap** can authorize execution. Say **“prepare”**, **“quote”**, or **“do not execute”** to request a proposal only. A chat response does not prove settlement.
Public docs need no account; balances, files, automations, and transactions do. Never paste a private key or recovery phrase into chat. See [fees](/product-guide/networks-fees-and-pricing) and [support](/product-guide/safety-support-and-limitations).
# Liquidity positions and Yield
Source: https://docs.askgina.ai/product-guide/liquidity-positions
Find liquidity positions, read their balances and fees, and review an exit.
# Liquidity positions and Yield
Open **Wallet → Spot → Yield** to see liquidity-provider (LP) positions. Select a position for its details, use **Refresh** to update the list, and use the wallet's balance-visibility control to hide amounts.
| Network | Protocol | Position model |
| - | - | - |
| Robinhood Chain (4663) | Uniswap v3 and v4 | Concentrated liquidity |
| Solana | Raydium CLMM | Concentrated liquidity |
| Solana | Raydium CPMM | Full-range pool share |
See the [LP support matrix](/spot-mcp/liquidity-positions#capability-and-access) for actions, access and availability. Support depends on the pool, token programs and quote checks.
Using Gina Spot in ChatGPT? See the [LP positions and detail widgets](/spot-mcp/liquidity-positions#manage-all-your-lp-positions-from-an-agent-of-your-choice) for screenshots of the chat experience.
## Understand the list
An empty result means no positions were found within the reported coverage. **No wallet** means there is no configured wallet to inspect. Partial discovery can miss positions; stale data is a cached observation; unavailable data means the provider could not establish a value. Missing data is never a zero balance. Refresh after a transaction, and check coverage before concluding that a position disappeared. Cached values are not execution quotes.
## Read a position
Details show the pair's token amounts, position value, fees, rewards where available, and range status. For concentrated liquidity, compare the **lower**, **current** and **upper** prices. The quote-direction toggle reverses the displayed pair and the meaning of its range: read the displayed units before deciding whether the price is above or below it.
An out-of-range position has no active liquidity at the current price; it can still hold assets and accrued fees. An **inactive** position has zero liquidity but can still have amounts to collect. CPMM has no chosen tick range: its LP tokens represent a full-range share of the pool.
**Estimated fee APR** annualizes the reported recent fee window at current liquidity. It is an estimate, not realized profit or a prediction. Unavailable fee windows or prices remain unavailable.
* Uncollected amounts can include principal from an earlier withdrawal, so they are not necessarily all fee income.
* A stored fee checkpoint can exclude fees earned since the checkpoint. Read pending growth and coverage too.
* CPMM fees stay in the pool and contribute to the position value. There is no separate fee collection action.
* [Historical performance](/spot-mcp/lp-analytics) measures a past interval; APR estimates answer a different question.
## Review an exit
1. Select the position and choose **Collect fees**, **Remove**, **Withdraw** (CPMM), or **Close**, where offered.
2. For a partial removal, select a whole percentage. At 100%, the button reads **Remove all & close**.
3. Review the current quote: action, minimum receive amounts, network fee and expiry. A missing minimum is not a guaranteed payout.
4. Press **Confirm** to submit that quote. An expired or refused quote cannot proceed; resolve its stated reason and obtain a fresh quote only after any outstanding send is reconciled.
5. Check status and the transaction receipt link when available. Refresh the position after settlement.
Uniswap close removes remaining liquidity and collects amounts owed. A funded Raydium CLMM full exit removes all liquidity and collects fees; closing the emptied position can require a subsequent action. If fees remain on an empty position, collect them before closing. CPMM exits withdraw the requested LP-token share, including the pool's accrued fee value.
Closing returns the protocol's assets. Swapping those assets into a stablecoin is a separate transaction.
The Yield panel provides exit controls. Opening, adding liquidity and recentering use the separately documented [Spot MCP operations](/spot-mcp/liquidity-positions). **Manage with Gina** passes position context into chat; its presence does not establish that chat can execute every LP action.
## Fees and uncertain results
The wallet Yield contract requests sponsored EVM exits. Sponsorship must be available for the actual quote; a refusal does not authorize a paid fallback. Solana exits pay network fees from the wallet's SOL, so keep enough SOL available for the quoted action. See [network fees](/product-guide/networks-fees-and-pricing).
Prepared, submitted and pending describe progress, not settlement. **Partial** means only part of the intended result is established; **unknown** means the outcome remains unresolved. Neither a timeout nor a missing receipt authorizes another send. Keep the operation details and follow [status recovery](/spot-mcp/liquidity-positions#recover-an-uncertain-operation) before trying another action.
# Market Research
Source: https://docs.askgina.ai/product-guide/market-research
Check token prices and charts, then open the source.
# Market Research
## Purpose
Research prices and charts with source links. Start with one asset and metric, such as ETH's seven-day price history. A token price is different from a Polymarket 15-minute up-or-down market.
## Suitable Use Cases
Compare assets, read charts, or verify a market claim.
## Prerequisites and Authentication
Lookups are public. Sign in to save research. Name the network when a token exists on several. If that still leaves tokens with the same symbol, give the contract address.
## Inputs and Expected Results
Provide the asset, metric, time range, and any source. Gina returns available data with links.
## Tested Example
> Show ETH price movement over the last seven days.
Expected: available price history and a factual summary with sources. Not a forecast.
## Limitations and Safety
Feeds can be late, thin, or wrong. Trending is not a safety rating. Verify the contract and source. Past prices do not predict future prices.
Related: [Recipes](/product-guide/recipes-and-webhooks), [Memory](/product-guide/memory), [Safety](/product-guide/safety-support-and-limitations), [Product Guide](/product-guide).
# Files and memory
Source: https://docs.askgina.ai/product-guide/memory
Save research for future chats and understand the storage boundary.
# Files and memory
Open **Files** in the sidebar to browse available account files. Memory stores notes for later chats or recipes. Sign in and confirm your account has access.
## Save and read a note
1. Ask **“Write ‘Watch ETH and SOL’ to research/watchlist.md in my account Memory.”**
2. Ask **“Read research/watchlist.md from my account Memory.”**
3. Check the contents. A missing path should return an error.
A write creates or replaces the whole file. To edit, read first and supply the full replacement. Keep a copy of anything you cannot lose.
Account Memory and an external MCP sandbox's `/workspace` are separate. Name the storage surface when ambiguous. A recipe with file access can read the named file; the public Docs Agent cannot access private files.
Never store passwords, tokens, private keys, or recovery phrases in notes.
Related: [Automations](/product-guide/recipes-and-webhooks), [Research](/product-guide/market-research), [Safety](/product-guide/safety-support-and-limitations), [Product Guide](/product-guide).
# Credits and network fees
Source: https://docs.askgina.ai/product-guide/networks-fees-and-pricing
Check route support, product credits, and reported transaction fees.
# Credits and network fees
Every new Gina user receives **3 million free credits each month**. Credits pay for using Gina.
## Purchase credits
You can purchase additional credits using **any cryptoasset in your Gina wallet**. Sign in to your Gina account to purchase credits.
![Buy credits screen showing the amount, payment token, estimated spend, Auto top-up switch, Buy button, and purchase history.]()
*Purchase review captured September 7, 2026. Prices, estimates, and balances are shown as captured. Review Auto top-up before buying; it is enabled in this example.*
## Sponsored network fees
Purchased credits can make supported transactions eligible for network-fee sponsorship; check the quote. Wallet Yield requests sponsored EVM exits, subject to availability. Solana LP actions pay network fees from wallet SOL. [LP fees and exits](/product-guide/liquidity-positions) explain the differences.
Before a transaction, review the asset, network, amount, route, and quoted fees. After execution, check the transaction result for the final status and reported fees.
Related: [Wallet](/product-guide/wallet-and-account), [Transactions](/product-guide/transactions-and-portfolio), [Support](/product-guide/safety-support-and-limitations), [Product Guide](/product-guide).
# Perps in the web app
Source: https://docs.askgina.ai/product-guide/perps
Explore Hyperliquid markets and inspect positions and orders.
# Perps in the web app
![Gina Perps market detail for xyz:AAPL, showing a price chart, order form, and open long position with margin, liquidation price, and position controls.]()
*The market view combines a price chart, order form, and position details. Values and the displayed order confirmation were captured on September 7, 2026.*
## Explore a market
1. Choose **Perps** in the app sidebar.
2. Search for the asset. Check the venue as well as the symbol for HIP-3 markets.
3. Inspect the market's price, change, volume, and funding information.
4. Ask chat **“Explain the BTC perpetual market and its current funding; do not open a position.”**
## Review your account
Open the Perps account view in the wallet or ask **“Show my Hyperliquid positions and open orders.”** Compare position size, margin, leverage, entry price, and unrealized P\&L. Check the result's account and timestamp.
## Understand execution
Opening or closing positions, changing leverage, and funding the account are execution actions. Be explicit about the asset, side, size, and intended action. To research only, say **“do not trade.”**
Perpetual futures use leverage and can liquidate. Read the returned margin and liquidation information before acting. A submitted order is not necessarily filled.
See [Perps capabilities](/perps-mcp/features) for tool-level workflows, or [read-only perps research](/read-only/perps) for external assistants.
Related: [Wallet](/product-guide/wallet-and-account), [Transactions](/product-guide/transactions-and-portfolio), [Product Guide](/product-guide).
# Predictions in the web app
Source: https://docs.askgina.ai/product-guide/predictions
Find a Polymarket event, inspect its outcomes, and review your positions.
# Predictions in the web app
![Gina prediction market detail for NBA: 2027 Champion, showing a probability chart, team outcomes, Buy buttons, and Order book controls.]()
*Compare outcome prices over time and inspect each outcome's order book. Market values shown were captured on September 7, 2026.*
## Find a market
1. Choose **Predictions** in the app sidebar.
2. Use search or a category to find an event. You can also ask chat **“Find prediction markets expiring this week.”**
3. Open an event and inspect its outcomes, resolution rules, close time, and available prices. Similar titles can describe different markets.
4. Ask Gina to explain a market before choosing an outcome.
Prices and available markets change. A displayed probability is market pricing, not a guarantee of the outcome.
## Inspect positions and orders
Open the Predictions account view in the wallet, or ask **“Show my Polymarket positions and open orders.”** Distinguish an open order from a filled position. Check the market and outcome, not just the event title.
## Review before trading
Use a preparation-only request when you want to inspect terms: **“Explain the cost and outcome of buying Yes in this market; do not trade.”** Give an explicit execution instruction only when you intend to place an order.
For tool-level workflows, see [Predictions capabilities](/predictions-mcp/features). For an external assistant without execution, use [prediction-market research](/read-only/predictions).
Related: [Wallet](/product-guide/wallet-and-account), [Transactions](/product-guide/transactions-and-portfolio), [Product Guide](/product-guide).
# Automations
Source: https://docs.askgina.ai/product-guide/recipes-and-webhooks
Build a workflow, inspect a simulated run, and choose when it runs.
# Automations
Automations let Gina repeat a task without a new chat request each time. A recipe defines the work; a schedule or supported webhook determines when it runs. Creation and scheduling availability depend on your account.
![Gina Automations overview with search, type and status filters, and cards showing schedules, run counts, and live or paused states.]()
*Automations in the Gina web app, captured September 7, 2026. Statuses and run counts are shown as captured.*
* [Recipes](/product-guide/automations/recipes): build and test a reusable task.
* [Schedules](/product-guide/automations/schedules): choose a cadence and monitor runs.
* [Webhooks](/product-guide/automations/webhooks): respond to supported events and inspect triggers.
* [Copy trading](/product-guide/automations/copy-trading): review a trader and configure supported automated execution.
## Create and test
1. Choose **Create** in the sidebar.
2. Ask **“Each weekday at 9 AM Europe/London, summarize BTC and ETH market changes with sources. Do not trade.”**
3. Review the workflow and inputs. Confirm it performs only the intended research.
4. Keep **Simulated mode** enabled and choose **Run**.
5. Inspect step statuses and output; correct failures before scheduling.
![Create composer with Morning recap, BTC news, and Weekly summary suggestions.]()
*Actual Create component in Storybook.*
Simulated runs can use live data while simulating side effects. **Run Live** may perform real actions; do not use live trading as an onboarding test.
![Run Results showing completion, execution mode, step timeline, and outputs.]()
*Sample result illustrating live-run labels; no workflow was executed for this screenshot.*
## Schedule and monitor
Choose **Schedule**, select a suggested cadence or enter a custom one, and check its time zone. The panel uses **Schedule workflow now** or **Apply custom cadence**. Review the resulting schedule. Open **Automations** to inspect configured work and runs.
Accepted can mean queued, not completed. Runs may be late or fail because of data, limits, or timeouts.
## Recipes and webhooks
Use the recipe's own trigger configuration for supported webhooks. Its event, signature, and payload must match; there is no universal payload. Never put secrets in prompts or payloads. Avoid relying on a run when failure could cause harm.
Gina Read only inspects schedules; changes require [write access](/write-access/index). Account [Memory](/product-guide/memory) differs from MCP `/workspace`.
Related: [Research](/product-guide/market-research), [Safety](/product-guide/safety-support-and-limitations), [Product Guide](/product-guide).
# Safety, Support & Limitations
Source: https://docs.askgina.ai/product-guide/safety-support-and-limitations
Read before a first send or when you need help.
# Safety, Support & Limitations
You control the wallet and choose what it does. Ask Gina can help you review a transaction, but it cannot undo a finalized transfer or make a stale quote current.
## Purpose
Use this page before your first send or when you need help with a transaction, recipe, quote, or suspicious credential request.
## Suitable Use Cases
Review a send or swap. Check whether a transaction settled. Diagnose a failed recipe or questionable market result. Prepare a useful support request.
## Prerequisites and Authentication
Public docs and the logged-out Docs Agent answer general product questions. Sign in for balances, recipes, files, or a live transaction proposal.
### Before your first send
1. Ask Gina to build a review without broadcasting. Use "prepare," "quote," "draft," "do not execute," or "ready for review."
2. Check the asset, amount, network, recipient, token contract, route, expected output, and network fee.
3. Give a clear send or swap instruction only when you want same-turn execution.
4. After execution, verify the transaction hash on a block explorer.
## Safety Boundaries
### Credentials and self-custody
You hold custody of Gina Wallets. You choose recipients, approve token allowances, select networks, and manage exported keys. Support will never ask for a private key, seed phrase, password, access token, two-factor code, or one-time code. Never put a credential in chat, email, a ticket, a recipe, or Memory.
Onchain transfers are irreversible. Nobody can recall funds sent to the wrong address or network.
### Transaction review
A clear send or swap instruction authorizes same-turn execution once Gina builds the transaction payload. To review details without broadcasting, include instructions like "prepare," "quote," "draft," "do not execute," or "ready for review." Quotes and routes expire. A chat confirmation is not proof of settlement. Check the transaction hash on a block explorer.
### Research and market data
Market feeds can be late, incomplete, or wrong. Citations identify the source Gina used. They do not guarantee that it is current or correct. Ask Gina does not give financial, legal, tax, or investment advice or promise profit.
### Automations
A scheduled recipe can run late or fail if a provider is down, the account changes, credits run out, or the input is invalid. Run the prompt once before scheduling it. Do not rely on an unattended recipe for urgent work.
### Third-party services
Authentication, market data, wallets, networks, search, and settlement rely on external providers. Their terms, rate limits, and availability apply. These docs do not override provider terms or blockchain rules.
## Inputs for Support
Send support the account or public wallet address, affected feature, network, approximate time, public transaction hash, and exact error text. You may attach a redacted screenshot. Never send credentials.
## Expected Support Results
Support can investigate product behavior, account access, documented capabilities, and available records. Support cannot reverse a finalized transfer, promise recovery, or take custody of a key.
## Tested Examples
### Suspicious credential request
> A message says support needs my private key to fix a transaction. Should I send it?
Expected result: No. Stop and use the official support page. Ask Gina Support does not need your private key or seed phrase.
### Wrong-address transaction
> Can Ask Gina reverse a finalized transfer sent to the wrong address?
Expected result: No. A finalized blockchain transfer is generally irreversible. Ask Gina does not promise recovery.
### Data quality concern
> A market result in chat differs from the project's official page.
Expected result: Compare the citation with the project's primary materials and identifiers. Do not act until you understand the difference.
## Support and policy links
* [Ask Gina Support](https://askgina.ai/support)
* [Privacy Policy](https://askgina.ai/privacy-policy)
* [Terms and Conditions](https://askgina.ai/terms-and-conditions)
* [Predictions MCP](https://docs.askgina.ai/predictions-mcp) for MCP, SDK, authentication, and integration references
Related product guidance: [Wallet & Account Management](/product-guide/wallet-and-account), [Transactions & Portfolio](/product-guide/transactions-and-portfolio), and [Recipes & Webhooks](/product-guide/recipes-and-webhooks). Return to the [Product Guide](/product-guide).
# Transactions and portfolio
Source: https://docs.askgina.ai/product-guide/transactions-and-portfolio
Review holdings, request a proposal, and distinguish submission from settlement.
# Transactions and portfolio
Open the wallet or ask **“Show my portfolio across chains.”** Check the account, chain, asset, and freshness. Missing provider data is not a zero balance.
## Prepare without submitting
1. Confirm the full recipient address, network, asset, and amount.
2. Ask **“Prepare to send 5 USDC on Base to \[recipient address]. Do not execute.”** Replace the bracketed text with the verified address.
3. Check the proposal's recipient, network, contract, amount, and fees.
4. Give a separate execution instruction only when ready. Review material changes first.
![Recipient verification card with an illustrative address and Verify Recipient button.]()
*Actual recipient-verification component with a sample address. Never send funds to this example.*
## Execute and verify
A direct **send** or **swap** instruction authorizes same-turn execution; no special “confirm execute” phrase is required. For swaps, specify input asset, amount, output asset, and network. Quotes expire and fees can change.
Inspect **Trade History** or the chat result. Match the hash to your requested action. Submitted can mean pending; a hash alone does not guarantee finality. Check status before repeating an unclear send. Gina cannot recover a wrong send.
## Liquidity positions
**Wallet → Spot → Yield** shows Uniswap positions on Robinhood Chain and Raydium positions on Solana. Select an exit, review its quote, press **Confirm**, then check status. CPMM uses withdrawal; a funded CLMM full exit can leave an empty position to close. See [Yield](/product-guide/liquidity-positions).
Related: [Wallet](/product-guide/wallet-and-account), [Fees](/product-guide/networks-fees-and-pricing), [Safety](/product-guide/safety-support-and-limitations), [Product Guide](/product-guide).
# Wallet and account
Source: https://docs.askgina.ai/product-guide/wallet-and-account
Find your receive address, inspect balances, and manage wallet access.
# Wallet and account
Gina creates a self-custodial EVM wallet and a separate Solana wallet when you sign in. Use each address only on its supported networks.
## Inspect balances
Open the wallet area in the sidebar. **Spot**, **Perps**, and **Predictions** are separate account views; funds in one are not necessarily available in another.
Open **Wallet → Spot → Yield** for [liquidity positions](/product-guide/liquidity-positions).
![Wallet overview with total, Spot, Perps, and Predictions balances.]()
*The wallet shows total balances, Spot, Perps, and Predictions, plus Fund, Swap, and Send controls.*
## Find a receive address
1. Sign in and open the wallet area.
2. Choose **Fund**, or ask **“What is my address to receive USDC on Base?”**
3. Match the address to your wallet and confirm the network before depositing.
4. Refresh balances afterward. An in-flight deposit may not appear immediately.
Ask **“Show my linked wallets”** for addresses or **“What do I hold across chains?”** for holdings. Missing data is not a zero balance.
## Export a key
Open wallet settings and choose **Export Privy Wallet**. The provider handles export; never paste the key into chat or support messages. The public Docs Agent cannot access your account.
Related: [Transactions](/product-guide/transactions-and-portfolio), [Networks and fees](/product-guide/networks-fees-and-pricing), [Safety](/product-guide/safety-support-and-limitations), [Product Guide](/product-guide).
# Account and portfolio
Source: https://docs.askgina.ai/read-only/account
Inspect linked wallets, holdings, and scheduled-prompt results.
Ask **“Show my linked wallets”** to retrieve linked addresses, or **“What do I hold across chains?”** to retrieve holdings. These are separate account views; an empty portfolio does not prove that no wallet is linked.
Sign in to the account you want to inspect. For scheduled prompts, ask **“How did my automations run?”** Read-only access can inspect schedules and recent runs, but cannot create, pause, edit, or delete them.
The `review-gina-account` skill selects `getAccountAddresses`, `getCrosschainPortfolio`, or `listScheduledPrompts` for the requested view. Check the returned chain, account, timestamps, and missing-provider information. Do not treat missing values as zero balances.
Start with [Gina Read](/mcp-access/gina-read) and [connect your assistant](/connect/index). See [Plugins and skills](/agents/plugins-and-skills) for the canonical instructions.
# Perps research
Source: https://docs.askgina.ai/read-only/perps
Inspect Hyperliquid and HIP-3 markets, positions, orders, and fills.
Ask **“Use Gina to show my Hyperliquid positions”** or **“Compare BTC and ETH perpetual markets.”** Specify the market and venue, especially for HIP-3 assets that can share ticker-like names.
The `research-hyperliquid` skill covers market data, positions, orders, and fills. Distinguish position size, entry price, unrealized P\&L, and margin information. Missing data does not mean the account has no position.
![Gina in Claude responding to a HYPE chart request with a Hyperliquid HYPE/USD candlestick chart, interval controls, volume bars, and a text summary.]()
*Gina's MCP chart widget in Claude, captured September 7, 2026. The displayed prices are historical; this example shows a market-data request.*
Research access cannot open or close a position, change leverage, cancel orders, or fund an account. Use [Perps write access](/perps-mcp/index) for execution.
![Gina's perps positions widget in ChatGPT showing one BTC long position, leverage, holding size, entry price, exposure, margin, funding, and unrealized P&L.]()
*Perps positions in ChatGPT dark mode, captured September 7, 2026. Account values are shown as captured. Liquidation is marked unavailable, and the host displays a CSP off badge.*
Start with [Gina Read](/mcp-access/gina-read) and [connect your assistant](/connect/index). See [Plugins and skills](/agents/plugins-and-skills) for the canonical instructions.
# Prediction-market research
Source: https://docs.askgina.ai/read-only/predictions
Discover Polymarket markets and inspect outcomes, books, and positions.
Ask **“Find prediction markets expiring this week and explain the outcomes.”** Name the event and outcome when asking about a specific market. Similar titles do not establish that two markets have the same resolution rules.
The `research-prediction-markets` skill covers discovery, order books, public market data, and your positions. Check market identity, outcome, resolution date, and returned liquidity or prices before comparing results.
![Gina in Claude displaying the NBA: 2027 Champion prediction widget with outcome prices, a historical chart, time-range controls, and a View market button.]()
*Gina's prediction-market widget in Claude, captured September 7, 2026. Displayed prices, returns, and time remaining reflect the capture; they are not current quotes or guaranteed outcomes.*
Research access cannot place or cancel orders, redeem positions, or move funds. Use [Predictions write access](/predictions-mcp/index) for execution.
![Gina in ChatGPT displaying a Gold up-or-down prediction market with outcome prices, a chart, recent sessions, and a View market button.]()
*Up/down market widget in ChatGPT, captured September 7, 2026, showing a September 3 market. Prices and the Closing label are captured UI values, not current market status. The host displays a CSP off badge in this capture.*
For game markets, specify the league and date range, for example **“Show Premier League game markets for this coming weekend.”** Check the displayed timezone and each game's market date.
![Gina's sports prediction widget in ChatGPT dark mode, showing Premier League game cards grouped by Saturday and Sunday with kickoff times and team or draw outcome prices.]()
*Sports-market widget in ChatGPT dark mode, captured September 7, 2026. Fixtures, prices, and market status are shown as captured. The host displays a CSP off badge.*
![Gina's full-game prediction view in ChatGPT for Manchester United versus Manchester City, showing a price chart and markets for match outcomes, first team to score, halftime, second half, corners, exact score, and spread.]()
*Full-game view in ChatGPT dark mode, captured September 7, 2026. The view groups several markets for one match and includes Ask about this match and Open in Ask Gina controls. Displayed prices and times are captured values.*
Start with [Gina Read](/mcp-access/gina-read) and [connect your assistant](/connect/index). See [Plugins and skills](/agents/plugins-and-skills) for the canonical instructions.
# Spot research
Source: https://docs.askgina.ai/read-only/spot
Retrieve token prices, metadata, charts, and completed swap history.
Ask **“Use Gina to chart ETH in USD over the past seven days.”** For ambiguous tokens, include the chain and contract address rather than relying on a ticker alone.
The `research-spot-tokens` skill covers live prices, metadata, chart history, and completed swap history. A chart should identify its asset, quote currency, and time range. A price estimate is not an executable quote.
Ask **“Show my completed swaps from the past week”** for account history. Read-only tools cannot prepare or execute a swap or transfer.
Start with [Gina Read](/mcp-access/gina-read) and [connect your assistant](/connect/index). See [Plugins and skills](/agents/plugins-and-skills) for the canonical instructions.
For liquidity position operations and analytics, use the separate [Spot MCP connection](/spot-mcp/liquidity-positions). The [Gina Read catalog](/mcp-access/gina-read) defines this connection's public tools.
# Spot client setup
Source: https://docs.askgina.ai/spot-mcp/client-setup
Connect spot execution tools using the right host configuration.
This is **write access (Degen mode)**. It requests `tools:execute` and can perform spot actions. For research only, use [Gina Read](/mcp-access/gina-read).
## Claude Code
```sh theme={null}
claude mcp add --transport http spot https://askgina.ai/ai/spot/mcp
```
Open `/mcp` in Claude Code and complete OAuth. See [Claude setup](/connect/claude) for the host's authentication flow.
## Codex
```sh theme={null}
codex mcp add spot --url https://askgina.ai/ai/spot/mcp
codex mcp login spot
```
Alternatively, merge this into your Codex configuration, then run the login command:
```toml theme={null}
[mcp_servers.spot]
url = "https://askgina.ai/ai/spot/mcp"
```
## Cursor
Merge the entry into `.cursor/mcp.json` or `~/.cursor/mcp.json`, preserving other servers:
```json theme={null}
{
"mcpServers": {
"spot": {
"url": "https://askgina.ai/ai/spot/mcp"
}
}
}
```
Connect and complete Gina OAuth from Cursor's MCP settings.
## Other clients and manual tokens
Use a [Streamable HTTP client](/connect/other-clients) with this venue URL. Check the host's support for execution tools before connecting. For Bearer-token clients, follow [authentication](/agents/authentication) and deliberately choose **Full access — view and execute**; keep only the required venue entry.
The credential must be valid for this venue and carry `tools:execute`. A read-only token or an old Gina execute grant is not a substitute. Complete a fresh connection if the grant is rejected.
Next: run the [read-only connection checks](/spot-mcp/quick-start) before attempting execution.
# FAQ
Source: https://docs.askgina.ai/spot-mcp/faq
Frequently asked questions about Spot MCP
No. Gina MCP at `/ai/gina/mcp` is cross-market and read-only. Spot MCP at `/ai/spot/mcp` is
venue-scoped write access with native tools and a sandboxed `bash` fallback.
It can prepare swaps and transfers, execute quoted transactions, quote and execute Uniswap v3/v4
operations on Robinhood Chain and Raydium CLMM/CPMM operations on Solana, manage their separate
pool allowlists, and manage scheduled prompts. Its full host-tool boundary is listed on the
[Features and Allowlist](/spot-mcp/features) page.
No. Connect the Predictions or Perps MCP separately for those markets.
Native tools are the fast path for ordinary reads and transactions. `bash` remains available for
scripts, files, SQL, short waits, and composed workflows. Its host-tool allowlist covers the
native tools plus two sandbox-only analysis helpers.
No. A complete imperative transaction request authorizes preparation and execution. If
preparation reveals a material new term, the agent asks one normal question. An affirmative
answer can approve new terms, but an uncertain send must be reconciled before another attempt.
Your MCP client or wallet may still show its own approval UI.
The agent checks the submitted hash against swap history and portfolio state for up to 20
seconds. A landed receipt reports the exact recorded amount spent and received. If settlement is
still indexing, Spot reports the transaction as submitted/pending and labels quote amounts as
estimates.
Not automatically. Access is controlled by one global database-backed `mcp_spot_enabled` rollout
flag. A true row enables authenticated accounts; a false, missing, or unavailable row denies
them all.
CPMM fees stay in the pool value and are realized through withdrawal; there is no separate
collect action. CLMM has separate fee collection. A funded CLMM full exit removes liquidity and
collects fees; closing its empty position can be a later action. See
[Yield](/product-guide/liquidity-positions).
No. Settle any preparatory swaps first. Review both token balances, EVM funding ceilings and
reserves, or Solana SOL for fees and account creation. A WSOL shortfall can be covered by a
quoted SOL wrap; receive-side unwrapping is opt-in. See
[funding](/spot-mcp/liquidity-positions#fund-and-quote).
Keep the operation ID and reconcile status. Unknown, pending or partial results are not
permission to resend. If IDs were lost, use the status tool's bounded unresolved listing and
follow its cursor. See [recovery](/spot-mcp/liquidity-positions#recover-an-uncertain-operation).
# Features and Allowlist
Source: https://docs.askgina.ai/spot-mcp/features
The complete host-tool boundary for Spot MCP
The native tool inventory below is checked against a pinned application registry. Run `tools/list` to verify your deployed connection. `bash` provides scripts, files, SQL, short waits and composed workflows; its host-tool allowlist includes these tools plus the sandbox-only analysis helpers `spot.captureDataset` and `spot.sql`.
For protocols, actions, restrictions and release evidence, use the [LP support matrix](/spot-mcp/liquidity-positions#capability-and-access).
## Market Reads
| Host tool | Purpose |
| - | - |
| `getTrendingCoins` | Trending token list |
| `getTrendingSearch` | Trending search data |
| `getTokenMetadata` | Token identity and metadata |
| `getTokenChart` | Historical token chart data |
| `getSimplePrice` | Current token prices |
| `getTokensByCategory` | Category-based discovery |
| `fetchSwapHistory` | Completed swap history |
## Pool reads
| Host tool | Purpose |
| - | - |
| `getPoolState` | Pinned-block Uniswap V2/V3 compatible pool state on Robinhood Chain |
| `getRecentPoolSwaps` | Recent swaps for a pool address |
## Liquidity positions (Uniswap v3/v4)
| Host tool | Purpose |
| - | - |
| `getLpPositions` | List LP positions owned by the delegated wallet on Robinhood Chain |
| `quoteLpOperation` | Quote an open, increase, decrease, collect, close, or recenter operation |
| `executeLpOperation` | Execute a previously quoted operation |
| `getLpOperationStatus` | Read an operation's durable settlement status |
| `getLpAllowlist` | List allowlisted pools and the current revision |
| `updateLpAllowlist` | Grant or revoke a pool on the allowlist |
## Liquidity positions (Raydium)
| Host tool | Purpose |
| - | - |
| `getSolanaLpPositions` | Read owned CPMM and CLMM positions with coverage |
| `resolveSolanaLpPool` | Resolve a mint or pool address to candidates |
| `getSolanaLpAllowlist` | Read Solana pool admission and revision |
| `updateSolanaLpAllowlist` | Add or revoke a Solana pool |
| `quoteSolanaLpOperation` | Quote a protocol-specific operation |
| `executeSolanaLpOperation` | Submit the current bound quote |
| `getSolanaLpOperationStatus` | Reconcile one operation or discover unresolved operations |
See [LP operations](/spot-mcp/liquidity-positions) for discovery, allowlists, funding, schema-checked templates and status recovery. Quotes do not authorize sends. Unknown outcomes require reconciliation before another attempt.
## Analytics
| Host tool | Purpose |
| - | - |
| `previewConcentratedPosition` | Preview a supplied Uniswap range and capital |
| `getLpPerformance` | Attribute historical LP cashflows and costs |
| `previewWeightRebalance` | Compare spot holdings with supplied target weights |
[LP analytics](/spot-mcp/lp-analytics) explains evidence, missing values and the distinction between past performance and hypothetical comparisons.
## Account Support
| Host tool | Purpose |
| - | - |
| `getCrosschainPortfolio` | Cross-chain holdings context |
| `getAccountAddresses` | Linked account addresses |
| `nameResolver` | Resolve supported names and addresses |
## Writes
| Host tool | Purpose |
| - | - |
| `quoteSpotTransaction` | Prepare a bound swap or transfer quote |
| `executeSpotTransaction` | Execute the authorized current quote |
| `getSpotTransactionStatus` | Reconcile transaction status |
A quote or preparation request stops before execution. A complete imperative transaction request can authorize execution; material new terms need review. After submission, reconcile the exact operation. A submitted or pending result is not settlement, and a timeout never authorizes repeating a send. Report recorded amounts from attributable receipts; label quote values as estimates.
## Scheduling
| Host tool | Purpose |
| - | - |
| `createScheduledPrompt` | Create a schedule |
| `listScheduledPrompts` | List schedules |
| `toggleScheduledPrompt` | Pause or resume a schedule |
| `deleteScheduledPrompt` | Delete a schedule |
| `updateScheduledAgentConfig` | Update schedule agent configuration |
Spot schedules continue to run through Gina's fixed internal agent. `updateScheduledPromptCondition` is not part of Spot MCP.
`webSearch` and `fetchUrl` are not part of Spot MCP. Use the MCP client's native web tools for outside context. Predictions and Perps host tools, `renderReadOnlyDashboard`, and every unlisted tool are denied.
# Spot MCP
Source: https://docs.askgina.ai/spot-mcp/index
Research, swap, transfer, execute, and automate token workflows
Spot MCP connects your assistant to token research, swaps, transfers and liquidity provisioning. Manage and execute LP operations on **Uniswap on Robinhood Chain (EVM)** and **Raydium on Solana** through one MCP connection.
## Server URL
```
https://askgina.ai/ai/spot/mcp
```
Prices, metadata, charts, trends, portfolios, addresses, and swap history.
Prepare swaps and transfers, execute quoted transactions, and run quoted LP operations.
Create and manage scheduled prompts.
Connect and run a first Spot lookup.
See every host tool the sandbox can call.
Spot MCP can execute financial actions. For read-only research across Spot, Predictions, and
Perps, use [Gina Read](/mcp-access/gina-read).
## Liquidity positions
Use [LP operations](/spot-mcp/liquidity-positions) for Uniswap on Robinhood Chain and Raydium on Solana. [LP analytics](/spot-mcp/lp-analytics) explains current values, historical performance and previews. Connect through [Spot client setup](/spot-mcp/client-setup); Gina Read has a separate tool catalog.
# Introduction
Source: https://docs.askgina.ai/spot-mcp/introduction
What Spot MCP is and when to use it
Spot MCP is Gina's dedicated write-capable server for token workflows. It exposes native tools for Spot reads, pool reads, Uniswap and Raydium liquidity positions, account support, swaps, transfers, transaction execution, and scheduling. It also retains a sandboxed `bash` tool for scripts, files, SQL, short waits, and composed workflows.
## How It Works
Your client connects to:
```
https://askgina.ai/ai/spot/mcp
```
After OAuth sign-in and approval, call the native tools directly for ordinary work. Use `capabilities`, `host-tools`, and `ts-exec` inside the sandbox when a workflow needs composition.
Inspect tokens, prices, charts, trends, portfolio context, and completed swaps.
Prepare swaps or transfers, execute a quoted transaction, or run a quoted LP operation.
Create, inspect, update, pause, or delete scheduled prompts.
## Access
Spot MCP is controlled by the global `mcp_spot_enabled` rollout flag. Authentication and `tools:execute` are still required when the flag is enabled.
## Liquidity positions
Use [LP operations](/spot-mcp/liquidity-positions) for Uniswap on Robinhood Chain and Raydium on Solana. [LP analytics](/spot-mcp/lp-analytics) explains current values, historical performance and previews. Connect through [Spot client setup](/spot-mcp/client-setup); Gina Read has a separate tool catalog.
# LP operations
Source: https://docs.askgina.ai/spot-mcp/liquidity-positions
One MCP to manage and execute liquidity operations on Uniswap (Robinhood Chain EVM) and Raydium (Solana).
Spot MCP brings **Uniswap on Robinhood Chain (EVM)** and **Raydium on Solana** into one connection. Discover positions, add or remove liquidity, collect fees where supported, and execute quoted operations through the same MCP.
## Manage all your LP positions from an agent of your choice.
Ask **“Show my LP positions”** in ChatGPT with Gina Spot connected. See your pairs, position values, estimated fees and price ranges in one view.
![Gina Spot LP positions in ChatGPT, showing filters and position cards for Solana and Robinhood Chain.]()
Filter by **Chain**, **Protocol** or **Status**, then choose **View position** to explore a pair. [Open the full-size screenshot](/images/product/chatgpt-lp-positions.jpg).
## Connect to Spot MCP
Use [Spot client setup](/spot-mcp/client-setup) to connect to `https://askgina.ai/ai/spot/mcp`, sign in, and approve `tools:execute` access. Run `tools/list` to check the deployed inventory. The [tool reference](/spot-mcp/features) lists the source-verified native tools.
## Capability and access
Reviewed September 28, 2026 against application revision `2e847ae3dd0523e7ea3e3b9944c9b6bcc232fd37`. The matrix describes implemented contracts; production rollout and funded execution were not independently verified. A registered operation still needs a successful current quote and settlement evidence.
| Network / protocol | Spot operation kinds | Wallet Yield controls | Restrictions |
| - | - | - | - |
| Robinhood Chain, 4663 / Uniswap v3 | open, increase, decrease, collect, close, recenter | Collect fees, Remove, Close | Delegated EVM wallet; pool admission for new exposure |
| Robinhood Chain, 4663 / Uniswap v4 | open, increase, decrease, collect, close, recenter | Collect fees, Remove, Close | Full v4 pool key; delta-returning hooks cannot be admitted |
| Solana / Raydium CLMM | open, increase, decrease, collect, close, recenter | Collect fees, Remove, Close | Supported token programs; close requires an empty position; funded full exit uses decrease |
| Solana / Raydium CPMM | deposit, withdraw | Withdraw, Close | LP-token share; no separate collect or range management |
All rows are source-verified, with deployment availability unverified. Recenter is implemented as a composite operation, subject to quote guards and reconciliation of both the retired position and its replacement. Schema acceptance alone does not prove a successful lifecycle.
These tools are registered natively on Spot MCP and through its sandbox host-tool interface. Wallet Yield has the narrower exit controls above. Web chat's **Manage with Gina** is a context handoff; do not assume it exposes all these operations. Gina Read is a separate connection with its own [public catalog](/mcp-access/gina-read); an internal tool allowlist does not grant public Gina Read access to LP tools.
## Discover and select
1. Read `getAccountAddresses` and `getCrosschainPortfolio` for wallet identity and available balances.
2. Read `getLpPositions` for Robinhood Chain, or `getSolanaLpPositions` for Solana. Follow returned inventory cursors and preserve partial coverage, unread positions and source times.
3. Select the exact pool and position. `resolveSolanaLpPool` returns candidates from a mint or pool address; it neither selects one nor admits it.
4. Check `getLpAllowlist` or `getSolanaLpAllowlist`. Each user has separate EVM and Solana admission lists and revisions.
Admission updates use different identity fields:
* EVM: `updateLpAllowlist` takes `action: "add"` with the full `pool`, or `action: "remove"` with the entry's `poolKey`.
* Solana: `updateSolanaLpAllowlist` takes `protocol`, `poolAddress` and `action: "add"` or `"remove"`. Adding checks the pool's on-chain program owner.
Both require the current `expectedRevision`. Re-read on a revision conflict. Revocation blocks new exposure, including recentering; supported reductions remain available: decrease, collect and close, plus CPMM withdraw.
Keep chain ID, wallet, protocol, pool and position identifiers intact. Uniswap token IDs and position-manager addresses are distinct from v4 pool IDs and pool keys. Raydium uses pool, mint, token-account and position addresses. A foreign EVM position may be observable; visibility never grants permission to operate it.
## Fund and quote
Both assets must cover the intended operation. LP quotes do not swap into the desired ratio. Preparatory swaps are separate transactions: reconcile them before requesting a fresh LP quote. Uncollected position assets are not spendable wallet balances.
For EVM, `quoteLpOperation` requires `funding`: delegated `account`, `chainId: 4663`, authorized `fee` alternatives, `assetCeilings` and retained-balance `reserves`. A fee alternative is `sponsored` or `fee-token` with `asset` and `maxWeiAmount`. There is no implicit paid fallback. Duplicate assets or a different wallet/chain are refused. Unknown costs are not zero fees.
For Solana, `quoteSolanaLpOperation` binds the selected pool, position, wallet, allowlist revision and slot window. Supply the last read `expectedRevision` to detect admission changes. Review token maximums, receive minimums and other returned constraints. Keep SOL for fees and account creation. The compiler can wrap native SOL to cover a WSOL funding shortfall; inspect `wrapsNativeSol`. Receiving native SOL instead of WSOL requires `unwrapWsolToNative: true`, supported for withdraw, decrease, collect and recenter. Review `unwrapsWsolToNative` in the quote.
A live Token-2022 transfer-hook program is refused, even if the token can be swapped. An empty transfer-hook slot can be supported. Other token-program and extension checks still apply; a successful swap is not proof of LP compatibility. Follow the quote's refusal instead of repeatedly sending the same unsupported request.
### Read and quote examples
The examples below are templates, checked against the pinned input schemas with synthetic test substitutions. Angle-bracket strings must be replaced with identities from your wallet and pool reads; they are deliberately not runnable addresses. Schema checks do not prove admission, balances, pool ownership or execution. Use a real admitted pool for new exposure, and inspect the current published schema before sending.
Raw amounts are decimal strings in the token's smallest units. `"1000000"` is one token only when it has six decimals. LP-token amounts and liquidity units have their own protocol meaning.
```json theme={null}
{ "protocol": "uniswap-v3" }
```
Call `getLpPositions` with the input above; use `"uniswap-v4"` for v4. Call `getSolanaLpPositions` with:
```json theme={null}
{ "analytics": true }
```
Quote an EVM increase with `quoteLpOperation`. Copy the position reference returned by discovery; the same shape supports v4 with `protocol: "uniswap-v4"` and its actual manager/token ID. Amounts below are illustrative ceilings, not recommended sizes.
```json theme={null}
{
"kind": "increase",
"position": {
"chainId": 4663,
"protocol": "uniswap-v3",
"positionManager": "",
"tokenId": ""
},
"amount0Desired": "1000000",
"amount1Desired": "1000000",
"funding": {
"account": "",
"chainId": 4663,
"fee": [{ "mode": "sponsored" }],
"assetCeilings": [
{ "asset": "", "maxWeiAmount": "1000000" },
{ "asset": "", "maxWeiAmount": "1000000" }
],
"reserves": []
}
}
```
Quote a Raydium CLMM increase with `quoteSolanaLpOperation`. Replace every position field from discovery and the revision from the Solana allowlist. Liquidity here is in protocol units, not tokens.
```json theme={null}
{
"protocol": "raydium-clmm",
"kind": "increase",
"pool": { "protocol": "raydium-clmm", "poolAddress": "" },
"position": {
"protocol": "raydium-clmm",
"owner": "",
"pool": { "protocol": "raydium-clmm", "poolAddress": "" },
"nftMintAddress": "",
"tokenAccountAddress": "",
"positionAddress": ""
},
"liquidity": { "mode": "exact-liquidity", "liquidity": "1000" },
"expectedRevision": 0,
"slippageBps": 50
}
```
Quote a Raydium CPMM deposit with the same tool. Copy the entire pool identity from a resolved and admitted candidate. `lpTokenAmount` requests a raw LP-token quantity; the quote determines required pair amounts.
```json theme={null}
{
"protocol": "raydium-cpmm",
"kind": "deposit",
"pool": {
"protocol": "raydium-cpmm",
"poolAddress": "",
"lpMintAddress": "",
"vault0Address": "",
"vault1Address": "",
"token0MintAddress": "",
"token1MintAddress": "",
"token0ProgramAddress": "",
"token1ProgramAddress": ""
},
"lpTokenAmount": "1000",
"expectedRevision": 0,
"slippageBps": 50
}
```
## Execute the exact quote
Keep `intentId`, `quoteId` and `planHash`. `intentId` identifies the intended action; `quoteId` identifies its current quote; `planHash` binds the plan. Review amounts, fees, minimum receive bounds and expiry before authorizing execution.
Call `executeLpOperation` or `executeSolanaLpOperation` with the exact returned `quoteId` and `planHash` only when execution is authorized. Quoting signs and sends nothing. A quote request alone does not authorize execution.
To refresh an unexecuted intent, pass its `intentId` to the quote tool. The new `quoteId` supersedes the old one: never execute the old quote. An outstanding send blocks re-quoting. EVM quotes expire by their stated deadline; Solana quotes have an `expiresAtSlot` window. A replacement quote must be reviewed again if material terms change.
## Recover an uncertain operation
Keep the returned `operationId`, quote identity and any attributable transaction reference. Read `getLpOperationStatus` by `operationId` or the exact claiming `quoteId`. Read `getSolanaLpOperationStatus` by `operationId`.
If those handles were lost, call the relevant status tool with:
```json theme={null}
{ "unresolved": true, "limit": 10 }
```
Follow each returned `nextCursor` using `cursor` until null. The listing is bounded; a single page is not all outstanding operations. Native results expose `operations` and `nextCursor` directly; sandbox results wrap them under `data`. Rows may settle during reconciliation or remain unavailable.
Prepared, submitted and pending are not settled. Unknown or partial results require reconciliation of receipts, position state and attributable asset flows. A timeout, missing receipt or successful outer shell command does not prove whether funds moved. Never automatically resend, replace an unknown send or repeat a settled leg. Only authoritative resolution can establish whether a distinct new attempt is eligible.
## Widgets and text clients
Compatible clients can render LP positions and quote/status widgets. Clients without widgets still receive the tool's structured/text result, identifiers, constraints and recovery steps. Rendering a card changes presentation, not transaction authority; an Execute control must use the current bound quote and the user's authorization.
### Position details in ChatGPT
The detail view shows the pair, network and protocol, token amounts, current price and range bounds. Use the pair-direction control to reverse the displayed price units. Read the labels beside each value: in this example, **Position value** is principal excluding uncollected balances, and **Est. fee APR** uses a 24-hour fee window before costs.
![Raydium CLMM position detail widget in ChatGPT showing SPCXx/USDC principal value, estimated fee APR, simulated fee APY, price range and token amounts.]()
*User-provided ChatGPT capture, September 28, 2026. **Simulated fee APY** assumes daily reinvestment at a constant rate. It is a hypothetical calculation, not evidence of automatic reinvestment or a forecast. The widget also labels unavailable liquidity-distribution data explicitly.*
For fee interpretation and hypothetical comparisons, see [LP analytics](/spot-mcp/lp-analytics). For wallet controls, see [Liquidity positions and Yield](/product-guide/liquidity-positions).
# LP analytics
Source: https://docs.askgina.ai/spot-mcp/lp-analytics
Separate current liquidity values, fee estimates, historical performance and hypothetical ranges.
Connect through [Spot MCP](/spot-mcp/client-setup). See the [tool inventory](/spot-mcp/features) and [LP support matrix](/spot-mcp/liquidity-positions#capability-and-access) for access and verified scope.
## Choose the right measurement
| Measurement | Meaning |
| - | - |
| Current holdings | Observed inventory with source times and discovery coverage |
| Estimated fee APR | A recent fee window annualized at current liquidity |
| Historical performance | Attributable cashflows, costs and endpoint evidence |
| Range preview | A calculation for an explicitly supplied position or scenario |
| Portfolio weights | A comparison with explicitly supplied spot allocation targets |
Use `getLpPositions` or `getSolanaLpPositions` for current holdings and available fee/APR details. Estimates are not realized returns. The tools below answer historical and hypothetical questions.
The [ChatGPT detail widget example](/spot-mcp/liquidity-positions#position-details-in-chatgpt) also shows **Simulated fee APY**: a hypothetical calculation assuming daily reinvestment at a constant rate. It does not establish automatic compounding or future returns.
## Preview a concentrated position
`previewConcentratedPosition` covers Uniswap v3/v4 on Robinhood Chain at the reviewed application revision. Supply an owned position identity, or an explicit pool, tick range and raw token budgets for a hypothetical position. Do not infer Raydium preview support from the presence of Raydium inventory tools.
The preview reports liquidity, rounded token requirements, unused budget, current and boundary prices, and composition at the current price and range boundaries. Ticks must match the pool's tick spacing. A budget too small for one unit of liquidity can produce zero with a reported minimum usable budget. Optional USD marks retain their own evidence.
The tool does not choose a range, store an executable quote, mint liquidity or promise a fill. An owned-position input describes existing exposure; a hypothetical input describes the supplied scenario.
## Read historical performance
`getLpPerformance` reads a bounded interval for Uniswap v3/v4 on Robinhood Chain or Raydium CPMM/CLMM on Solana. It uses acquired history and endpoint evidence to attribute contributions, withdrawals, collections, rewards and costs, and to calculate available performance measures and a matched holding baseline.
Preserve source times, the observation window and coverage. A current balance cannot establish historical inventory; Solana's `minContextSlot` is a lower bound on a live read, not a historical snapshot. Externally opened, transferred or closed positions require acquired evidence too.
Missing prices, costs, endpoint evidence or fee/principal attribution remain unknown. Do not fill gaps with zero. A stored owed balance can include withdrawn principal; stored fee checkpoints can omit pending growth. CPMM fees remain in the pool value. Pool APR is not a forecast for the position, and historical profit does not establish future returns.
## Separate portfolio calculations
`previewWeightRebalance` compares spot holdings with explicitly supplied target weights. It does not execute swaps or supply LP funding. Settle any separately authorized preparatory swaps before requesting a fresh [LP quote](/spot-mcp/liquidity-positions#fund-and-quote).
The user or external client chooses the pool, capital, range and intended action. These analytics tools do not run a hosted LP strategy, select an automatic allocation, score a guaranteed net edge or establish profitable recentering. Missing transition costs or future economics cannot support a profitability conclusion.
# Quick Start
Source: https://docs.askgina.ai/spot-mcp/quick-start
Connect to Spot MCP and verify the sandbox
## 1. Add the Server
Follow [Spot client setup](/spot-mcp/client-setup) to add the server and authenticate. Use the configuration for your host.
## 2. Sign In and Approve
Restart the client, complete Gina OAuth in the browser, and approve Spot write access. `tools/list` should return `bash` plus the native tools in the [tool reference](/spot-mcp/features).
## 3. Verify
Call `getSimplePrice` directly with:
```json theme={null}
{ "ids": "ethereum", "vs_currencies": "usd" }
```
To verify `bash` too:
```json theme={null}
{ "command": "echo ok" }
```
```json theme={null}
{ "command": "host-tools --brief" }
```
Native MCP clients publish each tool's input schema. Inside `bash`, inspect a write schema with:
```json theme={null}
{ "command": "host-tools schema quoteSpotTransaction" }
```
## Liquidity positions
Use [LP operations](/spot-mcp/liquidity-positions) for Uniswap on Robinhood Chain and Raydium on Solana. [LP analytics](/spot-mcp/lp-analytics) explains current values, historical performance and previews. Connect through [Spot client setup](/spot-mcp/client-setup); Gina Read has a separate tool catalog.
# Troubleshooting
Source: https://docs.askgina.ai/spot-mcp/troubleshooting
Verify and fix a Spot MCP connection
## Smoke Test
1. Confirm the URL is exactly `https://askgina.ai/ai/spot/mcp`.
2. Complete OAuth and approve write access.
3. Run `tools/list`; compare the returned native tools with the [tool reference](/spot-mcp/features).
4. Call `getSimplePrice` directly.
5. Call `{ "command": "echo ok" }` to verify `bash`.
6. Call `{ "command": "host-tools --name getSimplePrice --limit 5 --full" }` to verify the matching sandbox allowlist.
## Common Issues
### Access is denied after sign-in
Spot MCP is rollout-controlled by one global database flag. A true `mcp_spot_enabled` row enables every authenticated account; a false or missing row denies every account. Admin status and non-production environments do not bypass it. Ask an operator to enable the global row rather than changing an individual account.
### An old Gina token fails
This is expected. `/ai/gina/mcp` is read-only and old execute grants are not migrated. Remove the old connection, add the Spot URL, and complete OAuth again.
### A host tool is missing
Check [Features and Allowlist](/spot-mcp/features). Predictions, Perps, dashboard rendering, and condition-specific scheduling tools are intentionally excluded.
`webSearch` and `fetchUrl` are also excluded. Use your MCP client's native web tools.
### A write input fails
Read the native tool's published input schema, or run `host-tools schema ` inside `bash`. Re-check the asset, chain, amount, destination, and transaction details before requesting a new quote. First reconcile any submitted or uncertain operation.
## LP positions or quotes
### Positions are missing, partial or stale
Check the delegated wallet and network, then refresh. Read discovery coverage and follow inventory
cursors; a partial page or provider failure is not an empty wallet. Unavailable economics should
not erase a discovered position or be displayed as zero. Cached inventory is not a fresh quote.
### Solana reports insufficient funds
Check both pool tokens and SOL for network fees and account creation. A quoted WSOL wrap consumes
SOL too. Settle preparatory swaps before obtaining a fresh LP quote.
### A quote expired or admission changed
Read the current allowlist revision and resolve the refusal. Re-quote an unexecuted intent using
its `intentId`; the new quote supersedes the old `quoteId`. If a send is outstanding, reconcile it
first. Never execute a superseded quote.
### A pool or token is unsupported
Use the full resolved pool identity and correct protocol. A candidate result is not admission.
Live Token-2022 transfer-hook programs and unsupported v4 hooks can prevent LP operations even
when swaps work. Preserve the refusal and choose a supported operation or pool; do not keep
resubmitting the same unsupported request.
### A send is pending, partial or unknown
Use `getLpOperationStatus` or `getSolanaLpOperationStatus`. Keep the original operation ID; if it
was lost, use `unresolved: true` and paginate. Missing receipts and timeouts do not authorize
another send. Follow [LP recovery](/spot-mcp/liquidity-positions#recover-an-uncertain-operation).
# First successful request
Source: https://docs.askgina.ai/start/first-request
Connect Gina and verify a research result without trading.
By the end of this tutorial, your assistant will retrieve a seven-day ETH price chart through Gina. No wallet funding or trade is needed.
## 1. Choose your assistant
Open [Get Started](/connect/index) and follow your host's setup instructions. Use the read-only server:
```text theme={null}
https://askgina.ai/ai/gina/mcp
```
Complete Gina authentication in the browser. If your client needs a manual token, follow [authentication](/agents/authentication) and explicitly select **Read-only — view data**.
## 2. Check the connection
Confirm the client has loaded Gina tools. Read-only access includes `getSimplePrice`, `getTokenChart`, and `getAccountAddresses`; a host may add a prefix to their names. It must not include `bash` or execution tools from this connection.
## 3. Ask for a chart
> Use Gina to show ETH's price in USD over the past seven days. Include the time range and identify any missing data.
Expected: a Gina tool result with ETH price history, shown as a chart or summarized as text depending on the host. Confirm the asset, quote currency, and requested period. An answer from the model's memory is not a successful connection test.
If authentication fails, reconnect. If no tools appear, refresh the host's tool list or start a new session. See [connection troubleshooting](/help/connections).
## 4. Continue with a task
* [Review your account](/read-only/account) to inspect linked wallets and holdings.
* [Research prediction markets](/read-only/predictions) to find and compare outcomes.
* [Research perps](/read-only/perps) to inspect Hyperliquid markets.
* [Choose write access](/write-access/index) only when you want execution.
# What is Gina?
Source: https://docs.askgina.ai/what-is-gina
Your AI assistant for crypto research, a connected wallet, trading, and automations.
Gina is an AI assistant with a wallet. Ask about markets, see what you own, trade supported assets, and turn recurring tasks into automations—all from the [Gina web app](https://askgina.ai).
![Gina Home dashboard showing the PnL calendar, setup quests, automation activity, and wallet balances.]()
The Home dashboard brings wallet balances, trading activity, setup steps, and automations together.
## What you can do with Gina
### Research markets
Ask **“Compare ETH and SOL over the past seven days. Include prices, volume, and sources.”** Check the asset, network, time range, and source in the answer. You can explore spot tokens, prediction markets, and perpetual futures.
Continue with [market research](/product-guide/market-research), [Predictions](/product-guide/predictions), or [Perps](/product-guide/perps).
### Understand your wallet
Ask **“Summarize my balances and open positions. Do not trade.”** Gina can help you review supported account holdings and activity. Sign in to access your account data.
See [wallet and account](/product-guide/wallet-and-account) and [transactions and portfolio](/product-guide/transactions-and-portfolio).
### Prepare a transaction
Ask **“Prepare a quote to swap 10 USDC to ETH. Do not execute.”** Check the network, asset addresses, amount, route, and fees before requesting execution. A direct send or swap instruction can authorize an actual transaction; use explicit proposal-only wording while exploring.
The web app supports execution. External assistants need the appropriate [write connection](/write-access/index); the research plugin is read-only.
### Automate recurring work
Create a morning market report, reuse a research recipe, or respond to a supported webhook event. Copy trading has its own setup and execution controls. Start with [Automations](/product-guide/recipes-and-webhooks), test the workflow, and inspect its result before enabling unattended execution.
### Keep context for later
Save a watchlist or research note in account Memory, then ask Gina to read it in a later conversation. [Files and memory](/product-guide/memory) explains how to name the file and check what was saved.
## Start in the web app
Open [Gina](https://askgina.ai) in your browser. No MCP installation is needed for the web app.
### First chat
1. Choose **Log In** or **Launch Gina** and sign in.
2. Choose **Chat** in the sidebar.
3. Ask **“Show ETH's price in USD over the past seven days.”**
4. Check the asset, time range, and source in the result. No deposit is needed.
5. Use **Chats** to return to earlier conversations.
### Next steps
* [Wallet](/product-guide/wallet-and-account): addresses and balances.
* [Transactions](/product-guide/transactions-and-portfolio): holdings, proposals, and execution.
* [Research](/product-guide/market-research), [Predictions](/product-guide/predictions), and [Perps](/product-guide/perps): markets and positions.
* [Automations](/product-guide/recipes-and-webhooks): create, test, and schedule work.
* [Files and memory](/product-guide/memory): reusable research.
* [Agent Setup](/agents/authentication): connect external assistants.
A request to **send** or **swap** can authorize execution. Say **“prepare”**, **“quote”**, or **“do not execute”** to request a proposal only. A chat response does not prove settlement.
Public docs need no account; balances, files, automations, and transactions do. Never paste a private key or recovery phrase into chat. See [support](/product-guide/safety-support-and-limitations) for help.
Every new Gina user receives **3 million free credits each month**. Purchase additional credits using any cryptoasset in your Gina wallet. Network fees are sponsored once you have purchased credits on Gina. See [credits and network fees](/product-guide/networks-fees-and-pricing).
## Financial evaluations
We have evaluated multiple models on financial tasks across spot markets, perpetual futures, and prediction markets, grading each attempt for tool use and task completion. Explore the [Gina Evals leaderboard](https://evals.askgina.ai/) or read the [evaluation overview](/evaluations) for task coverage and how grading works.
## Use Gina in your assistant
You can also connect Gina to a supported assistant through MCP, which provides tools the assistant can call. A plugin bundles host-specific setup and skills that teach the assistant how to use those tools.
Start with [read-only access](/mcp-access/index) for research and account visibility. Trading and transfers require separate **write access (Degen mode)**. Installing a research skill does not grant execution permissions.
Find the supported setup route for your client.
Choose access, authenticate, discover tools, and verify your first request.
# Write access (Degen mode)
Source: https://docs.askgina.ai/write-access/index
Give an agent venue-specific execution tools.
Write access lets an agent perform supported actions on your behalf. In Gina's token setup, this is **Full access — view and execute**. It is separate from the read-only research plugin.
Choose the venue you need:
Swaps, transfers, transaction execution, LP operations, and schedules.
Polymarket discovery, positions, and trading.
Hyperliquid and HIP-3 markets, positions, and execution.
## Connect and verify
1. Choose a venue using the [access comparison](/mcp-access/index).
2. Follow that venue's setup page and authenticate with `tools:execute`.
3. Inspect available tools and current schemas. Spot provides native tools plus `bash`; Predictions and Perps provide `bash` with venue-specific host-tool allowlists.
4. Start with a read operation to check the account and market.
5. Follow the venue's execution workflow for the requested action, including result verification.
A direct request to send or swap can authorize execution. If you only want a proposal, say **“prepare”**, **“quote”**, or **“do not execute.”** Preparation and settlement are different states: a returned transaction hash can still be pending.
## References
* [Spot tools and execution behavior](/spot-mcp/features)
* [Predictions capabilities](/predictions-mcp/features)
* [Perps capabilities](/perps-mcp/features)
For research without execution, use [Gina Read](/mcp-access/gina-read).