# Troubleshooting

## Overview

There are several errors which can occur when using the Agentic Trading toolkit. 

### Contract Errors

These errors occur during on-chain trade execution.

| Error                       | Cause                                               | Fix                                      |
| --------------------------- | --------------------------------------------------- | ---------------------------------------- |
| `TokensInExceedsMax`        | Price moved above your `maxTokensIn` since quoting  | Re-quote and increase slippage tolerance |
| `TokensOutBelowMin`         | Price moved below your `minTokensOut` since quoting | Re-quote and increase slippage tolerance |
| `MarketNotOpen`             | Market is closed or settled                         | Check `market.status` before trading     |
| `SharesInExceedSupply`      | Selling more shares than your wallet holds          | Check position balance before selling    |
| `GrossTokensOutNotPositive` | Attempting to sell with no position                 | Position is empty — nothing to sell      |
| `ZeroTokensIn`              | `sharesOut` amount too small to register            | Use a larger share amount                |

### Environment Variable Errors

| Error                      | Cause                                                      | Fix                                                                                                                          |
| -------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Requires apiKey`          | `DELPHI_API_ACCESS_KEY` not set                            | Add it to your `.env` file — generate at [delphi-api-access-app.pages.dev](https://delphi-api-access-app.pages.dev/)         |
| `Requires rpcUrl`          | `GENSYN_RPC_URL` not set and network default not resolving | Set `DELPHI_NETWORK=testnet` or provide `GENSYN_RPC_URL` explicitly                                                          |
| `Requires privateKey`      | Using private key signing without `WALLET_PRIVATE_KEY`     | Set `WALLET_PRIVATE_KEY` in `.env` or switch to CDP signer                                                                   |
| `CDP signing requires ...` | Missing one or more CDP environment variables              | Ensure all four `CDP_*` variables are set: `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`, `CDP_WALLET_SECRET`, `CDP_WALLET_ADDRESS` |

### Wallet & Network Issues

Errors related to token bridging, balance lag, MetaMask, market or market action issues, and more. 

#### MetaMask Not Showing the Correct Balance

If MetaMask shows unexpected balances or token symbols after connecting to the Gensyn network:

1. Open MetaMask and go to **Settings** then **Networks**
2. Find the Gensyn network entry and click **Edit**
3. Verify the RPC URL matches: `https://gensyn-testnet.g.alchemy.com/public`
4. Verify the Chain ID matches: `685685`
5. Save and refresh the page

#### Bridge Transactions Not Appearing

After bridging tokens from Sepolia to Gensyn testnet, balances may take up to 5 minutes to reflect. 

If tokens still don't appear:

1. Check the transaction on the explorer to confirm it was sent
2. Verify you're viewing the correct network in MetaMask (Gensyn Testnet, not Sepolia)
3. Try switching away from the Gensyn network and switching back
4. Refresh MetaMask or the Delphi UI

#### Transactions Failing with Insufficient Funds

Your signer wallet needs both ETH (for gas) and USDC (for trading) on the Gensyn chain. 

If transactions fail:

1. Check your ETH balance: even read-only quote operations are free, but all write operations (buy, sell, approve, redeem) require gas
2. Check your USDC balance: Make sure you have enough to cover the trade amount plus slippage
3. If on testnet, use the bridge to transfer tokens from Sepolia

### Positions Showing Zero Shares

The positions API may return entries with `shares === "0"` for markets you previously participated in but fully exited. These are expected. They indicate historical participation, not current holdings. 

{% hint style="info" %}
Always check `BigInt(position.shares) > 0n` before attempting to redeem or liquidate.
{% endhint %}

### Market Not Found or Not Trading

* **Market shows as `awaiting_settlement`**: Trading deadline has passed. You cannot buy or sell, but the market hasn't been settled yet.
* **Market shows as `settled`**: Trading is closed. If you hold the winning outcome, you can redeem your position.
* **Market shows as `expired`**: Market expired without settlement. Positions are not redeemable.
* **Market not appearing in search**: There is currently no search functionality in the Delphi UI. Use `client.listMarkets()` with filtering to find markets programmatically, or browse by category and status.

### Slippage Failures (on Active Markets)

If your trades keep failing with `TokensInExceedsMax` or `TokensOutBelowMin`, the market is likely seeing high trading volume and prices are moving between your quote and execution.

Increase your slippage tolerance:

| Scenario                 | Recommended slippage |
| ------------------------ | -------------------- |
| Quiet market             | 1–2%                 |
| Active market            | 2–5%                 |
| Large trade (>$100)      | 5–10%                |
| Time-sensitive execution | 5%                   |

You can also try using *basis points* for precise integer arithmetic:

```typescript
const slippageBps = 200n; // 200 = 2%
const maxTokensIn  = tokensIn  * (10000n + slippageBps) / 10000n;
const minTokensOut = tokensOut * (10000n - slippageBps) / 10000n;
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gensyn.ai/tech/agentic-trading/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.