> ## 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.

> Manage yield.xyz projects, API keys, enabled yields, fee configurations, and reports via the Programmatic API. Use when the user wants to automate dashboard operations: creating projects, minting keys, enabling/disabling yields, configuring fees, pulling reports, or provisioning new client workspaces programmatically.

# SKILL

# Programmatic Access

Automate yield.xyz dashboard operations through the Programmatic API. This skill enables an AI agent to manage projects, API keys, yield enablement, fee configuration, and reporting without manual dashboard interaction.

## When to Use

Activate this skill when the user asks to:

* Create, list, update, or delete yield.xyz projects
* Generate, rotate, or revoke API keys for a project
* Enable or disable yield integrations for a project
* Configure deposit, management, or performance fees
* Pull transaction or staking reports across projects
* Set up automated provisioning for new clients or workspaces
* Query the status of fee configurations (REQUESTED, PROCESSING, LIVE)
* Work with the admin/programmatic API (not the standard Yield API)

## Authentication

The Programmatic API uses a separate **Admin API Key**, distinct from project-level Yield API keys.

All requests require:

```
X-ADMIN-API-KEY: YOUR_ADMIN_API_KEY
```

This key is obtained from the yield.xyz dashboard:

1. Log in to the yield.xyz dashboard as an owner or admin.
2. Open the **Programmatic Access** page, under **Admin API keys**.
3. Create an admin API key.

The admin key is scoped to your team. It is shown only once at creation time and must be stored securely. It is a separate credential from project API keys and is not part of the public API reference.

## Base URL

```
https://api.stakek.it
```

All programmatic endpoints are under `/v1/programmatic/`.

## Step-by-Step Instructions

### Step 1: Manage Projects

Projects are the top-level organizational unit. Typically one project per client, workspace, or environment.

**Create a project:**

```bash theme={null}
curl -X POST https://api.stakek.it/v1/programmatic/projects \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "description": "Production integration"}'
```

Response includes `id`, `name`, `description`, `teamId`, `createdAt`, `updatedAt`.

**List projects:**

```bash theme={null}
curl https://api.stakek.it/v1/programmatic/projects \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

**Update a project:**

```bash theme={null}
curl -X PATCH https://api.stakek.it/v1/programmatic/projects/{projectId} \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "autoComplaintBansEnabled": true}'
```

**Delete a project:**

```bash theme={null}
curl -X DELETE https://api.stakek.it/v1/programmatic/projects/{projectId} \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

### Step 2: Manage API Keys

API keys are scoped to a project. These keys authenticate Yield API requests through the `x-api-key` header.

**Create a key:**

```bash theme={null}
curl -X POST https://api.stakek.it/v1/programmatic/projects/{projectId}/keys \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key", "info": "Backend services"}'
```

**IMPORTANT:** The `apiKey` field is only returned at creation time. Store it immediately.

**List keys:**

```bash theme={null}
curl https://api.stakek.it/v1/programmatic/projects/{projectId}/keys \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

**Update a key:**

```bash theme={null}
curl -X PATCH https://api.stakek.it/v1/programmatic/projects/{projectId}/keys/{keyId} \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Key", "info": "Updated metadata"}'
```

**Delete (revoke) a key:**

```bash theme={null}
curl -X DELETE https://api.stakek.it/v1/programmatic/projects/{projectId}/keys/{keyId} \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

### Step 3: Enable / Disable Yields

Control which yield integrations are available per project. Integration IDs follow the pattern `{network}-{token}-{provider}-{type}` (e.g., `ethereum-eth-lido-staking`).

**List enabled yields:**

```bash theme={null}
curl "https://api.stakek.it/v1/programmatic/projects/{projectId}/yields/enabled?page=1&limit=50" \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

**Enable yields (bulk):**

```bash theme={null}
curl -X POST https://api.stakek.it/v1/programmatic/projects/{projectId}/yields/enabled \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"integrationId": "ethereum-eth-lido-staking"},
    {"integrationId": "optimism-usdt-aave-v3-lending"},
    {"integrationId": "arbitrum-eth-aave-v3-lending"}
  ]'
```

**Disable a single yield:**

```bash theme={null}
curl -X DELETE https://api.stakek.it/v1/programmatic/projects/{projectId}/yields/enabled/{integrationId} \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

**Disable yields (bulk):**

```bash theme={null}
curl -X DELETE https://api.stakek.it/v1/programmatic/projects/{projectId}/yields/enabled \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"integrationIds": ["ethereum-eth-lido-staking", "optimism-usdt-aave-v3-lending"]}'
```

### Step 4: Configure Fees

Fees are set per integration, per project. Values are in **basis points** (100 bps = 1%).

**Create a fee configuration:**

```bash theme={null}
curl -X POST https://api.stakek.it/v1/programmatic/projects/{projectId}/fee-configuration \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "optimism-usdt-aave-v3-lending",
    "depositFeeBps": 50,
    "performanceFeeBps": 1000
  }'
```

Fee configuration fields:

| Field | Type | Range | Description |
| - | - | - | - |
| `integrationId` | string | n/a | Target yield integration (required) |
| `depositFeeBps` | number | 1 to 10000 | Deposit fee in basis points |
| `managementFeeBps` | number | 1 to 10000 | Management fee in basis points |
| `performanceFeeBps` | number | 1 to 10000 | Performance fee in basis points |

Fee configuration lifecycle statuses:

| Status | Meaning |
| - | - |
| `REQUESTED` | Submitted, awaiting processing |
| `PROCESSING` | yield.xyz deploying onchain infrastructure (OAV or fee wrapper) |
| `LIVE` | Active and applied |
| `CHANGES_REQUESTED` | Update submitted, being processed |

**List fee configurations:**

```bash theme={null}
curl "https://api.stakek.it/v1/programmatic/projects/{projectId}/fee-configuration?page=1&limit=10" \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

**Update a fee configuration:**

```bash theme={null}
curl -X PATCH https://api.stakek.it/v1/programmatic/projects/{projectId}/fee-configuration/{feeConfigurationId} \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"performanceFeeBps": 500}'
```

Pass `null` for a fee field to remove it.

**Delete a fee configuration:**

```bash theme={null}
curl -X DELETE https://api.stakek.it/v1/programmatic/projects/{projectId}/fee-configuration/{feeConfigurationId} \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

### Step 5: Pull Reports

Query transaction and staking activity across all projects.

```bash theme={null}
curl "https://api.stakek.it/v1/programmatic/report-entries?page=1&limit=10&sort=createdAtDesc" \
  -H "X-ADMIN-API-KEY: $ADMIN_API_KEY"
```

Query parameters:

| Parameter | Type | Description |
| - | - | - |
| `projectId` | string | Filter by project |
| `integrationId` | string | Filter by yield integration |
| `walletAddress` | string | Filter by wallet address |
| `validatorAddress` | string | Filter by validator address |
| `status` | string | Filter by action status (SUCCESS, FAILED, PROCESSING, etc.) |
| `type` | string | Filter by action type (STAKE, UNSTAKE, CLAIM\_REWARDS, etc.) |
| `sort` | string | createdAtAsc or createdAtDesc |
| `page` | number | Page number (default: 1) |
| `limit` | number | Items per page (default: 10) |

## Provisioning Flow

When onboarding a new client or workspace, follow this sequence:

1. `POST /v1/programmatic/projects`: Create a project
2. `POST /v1/programmatic/projects/{projectId}/keys`: Mint an API key (store the `apiKey` value immediately)
3. `POST /v1/programmatic/projects/{projectId}/yields/enabled`: Enable a curated set of yields
4. `POST /v1/programmatic/projects/{projectId}/fee-configuration`: Apply fees (optional)
5. `GET /v1/programmatic/report-entries?projectId={projectId}`: Monitor activity

## Endpoint Reference

| Method | Endpoint | Purpose |
| - | - | - |
| POST | `/v1/programmatic/projects` | Create project |
| GET | `/v1/programmatic/projects` | List projects |
| PATCH | `/v1/programmatic/projects/{projectId}` | Update project |
| DELETE | `/v1/programmatic/projects/{projectId}` | Delete project |
| POST | `/v1/programmatic/projects/{projectId}/keys` | Create API key |
| GET | `/v1/programmatic/projects/{projectId}/keys` | List keys |
| PATCH | `/v1/programmatic/projects/{projectId}/keys/{keyId}` | Update key |
| DELETE | `/v1/programmatic/projects/{projectId}/keys/{keyId}` | Revoke key |
| POST | `/v1/programmatic/projects/{projectId}/yields/enabled` | Enable yields |
| GET | `/v1/programmatic/projects/{projectId}/yields/enabled` | List enabled yields |
| DELETE | `/v1/programmatic/projects/{projectId}/yields/enabled/{integrationId}` | Disable single yield |
| DELETE | `/v1/programmatic/projects/{projectId}/yields/enabled` | Disable yields (bulk) |
| POST | `/v1/programmatic/projects/{projectId}/fee-configuration` | Create fee config |
| GET | `/v1/programmatic/projects/{projectId}/fee-configuration` | List fee configs |
| PATCH | `/v1/programmatic/projects/{projectId}/fee-configuration/{id}` | Update fee config |
| DELETE | `/v1/programmatic/projects/{projectId}/fee-configuration/{id}` | Delete fee config |
| GET | `/v1/programmatic/report-entries` | List report entries |

## Error Handling

| Status Code | Meaning | Action |
| - | - | - |
| 400 | Invalid request body or parameters | Check field names, types, and required fields |
| 401 | Invalid or missing admin API key | Verify `X-ADMIN-API-KEY` header value |
| 403 | Forbidden: key doesn't have permission | Ensure the admin key belongs to the correct team |
| 404 | Resource not found | Check projectId, keyId, or feeConfigurationId |
| 429 | Rate limited | Wait and retry with backoff |
| 500 | Server error | Retry with exponential backoff (max 3 retries) |

## Edge Cases

* **Admin key vs project key:** The `X-ADMIN-API-KEY` is for programmatic/admin endpoints only. Project-level keys (`x-api-key`) are for the standard Yield API (discovery, balances, actions).
* **Key shown once:** The `apiKey` field on key creation is the only time the raw key value is returned. It cannot be retrieved again.
* **Fee deployment time:** Fee configurations with status `PROCESSING` may take time as yield.xyz deploys onchain infrastructure (OAV or fee wrapper contracts).
* **Soft deletes:** Deleting projects and keys are soft-deletes, the `deletedAt` field is set, and the resource stops functioning but is retained for auditing.
* **Pagination:** All list endpoints support `page` and `limit` query parameters. Check `hasNextPage` to determine if more results exist.
* **Curated bundles:** You can pre-define bundles of integration IDs (e.g., "Stablecoin Conservative") and enable them in a single bulk call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.