> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Guardrails

> Safety considerations when using AI for development

## Overview

Important safety considerations when using AI assistants for Yield.xyz development. Follow these guidelines to protect your integration and users.

***

## Security Guardrails

### Never Share API Keys

<Warning>
  **Never paste API keys in AI prompts.**

  ```
  // ❌ Bad
  "My API key is abc123xyz, why isn't it working?"

  // ✅ Good
  "My API key (a89db9a6***) returns 401, what could be wrong?"
  ```
</Warning>

### Never Share Private Keys or Seed Phrases

<Warning>
  **AI assistants should never see private keys, seed phrases, or wallet credentials.**

  If you need help with signing logic, use placeholder values:

  ```typescript theme={null}
  // ✅ Safe
  const privateKey = process.env.PRIVATE_KEY; // Never hardcode
  ```
</Warning>

### Don't Share User Data

<Warning>
  Don't include real user addresses or transaction data in prompts. Use test addresses or anonymize data.
</Warning>

***

## Code Review Guardrails

### Always Verify Generated Code

<Steps>
  <Step title="Read the Code">
    Understand what AI-generated code does before using it
  </Step>

  <Step title="Check API Calls">
    Verify endpoints and parameters match the [API Reference](/api-reference/getting-started)
  </Step>

  <Step title="Verify Types">
    Check that TypeScript types match the actual API response schemas
  </Step>

  <Step title="Test in Staging">
    Never deploy untested AI code to production
  </Step>

  <Step title="Security Review">
    Check for vulnerabilities, especially around transaction signing
  </Step>
</Steps>

***

## Common AI Mistakes

Watch for these common issues when using AI with Yield.xyz:

<AccordionGroup>
  <Accordion title="Outdated API patterns">
    AI may suggest v1 API patterns or deprecated endpoints. Always verify against the current [API docs](https://api.yield.xyz/docs).

    **v1 (deprecated):**

    ```json theme={null}
    { "addresses": { "address": "0x..." }, "args": { "amount": "1" } }
    ```

    **v2 (current):**

    ```json theme={null}
    { "address": "0x...", "arguments": { "amount": "1" } }
    ```
  </Accordion>

  <Accordion title="Missing error handling">
    AI often generates happy-path code. Add proper error handling for:

    * Network failures
    * API errors (400, 401, 404, 429, 500)
    * Transaction failures
    * Wallet connection issues
  </Accordion>

  <Accordion title="Hardcoded values">
    Watch for hardcoded:

    * API URLs (should use environment variables)
    * Yield IDs (may change or be deprecated)
    * Network names
    * Token addresses
  </Accordion>

  <Accordion title="Incorrect async handling">
    Verify proper await/async patterns:

    ```typescript theme={null}
    // ❌ Bad - missing await
    const action = createEnterAction(yieldId, address, amount);

    // ✅ Good
    const action = await createEnterAction(yieldId, address, amount);
    ```
  </Accordion>

  <Accordion title="Wrong transaction execution order">
    Yield.xyz returns transactions that must be executed in order (synchronous pattern). Don't parallelize:

    ```typescript theme={null}
    // ❌ Bad - parallel execution
    await Promise.all(action.transactions.map(tx => signAndBroadcast(tx)));

    // ✅ Good - sequential execution
    for (const tx of action.transactions) {
      await signAndBroadcast(tx);
    }
    ```
  </Accordion>

  <Accordion title="Missing passthrough for manage actions">
    The passthrough field is required for manage actions and comes from the balance endpoint:

    ```typescript theme={null}
    // ✅ Correct
    const balance = await getBalances(yieldId, address);
    const passthrough = balance.pendingActions[0].passthrough;
    await manageAction(yieldId, address, "CLAIM_REWARDS", passthrough);
    ```
  </Accordion>
</AccordionGroup>

***

## Verification Checklist

Before deploying AI-generated code:

<CardGroup cols={2}>
  <Card title="API Endpoints" icon="link">
    * Correct base URL (`https://api.yield.xyz`)
    * Correct HTTP methods
    * Correct path parameters
    * Correct request body structure
  </Card>

  <Card title="Authentication" icon="key">
    * API key in `x-api-key` header
    * Key loaded from environment
    * No hardcoded keys
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    * All API calls have try/catch
    * Rate limiting handled
    * User-friendly error messages
  </Card>

  <Card title="Transaction Flow" icon="arrow-right">
    * Sequential execution
    * Hash submission after each tx
    * Status polling implemented
  </Card>
</CardGroup>

***

## Testing AI-Generated Code

<Steps>
  <Step title="Unit Tests">
    Test individual functions with mocked API responses
  </Step>

  <Step title="Integration Tests">
    Test against testnet yields (e.g., `ethereum-holesky`)
  </Step>

  <Step title="Manual Testing">
    Walk through flows manually before production
  </Step>

  <Step title="Code Review">
    Have a team member review the implementation
  </Step>
</Steps>

***

## Resources

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/getting-started">
    Official API documentation
  </Card>

  <Card title="OpenAPI Spec" icon="file-code" href="https://api.yield.xyz/docs.yaml">
    Machine-readable API specification
  </Card>

  <Card title="Swagger UI" icon="code" href="https://api.yield.xyz/docs">
    Interactive API explorer
  </Card>

  <Card title="Security Docs" icon="shield" href="/documentation/shield-security/security-overview">
    Security best practices
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/documentation/quickstart">
    Integration guide
  </Card>

  <Card title="Security" icon="shield" href="/documentation/shield-security/security-overview">
    Security best practices
  </Card>
</CardGroup>