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

# API Walkthrough

> End-to-end example: create, manage, observe, and integrate a strategy through the external API.

This page is a practical workflow for engineers who want to use the API from zero to production-style integration.

Scenario:

* You want to create a Strategy programmatically.
* The Strategy should focus on safe new launches with minimum liquidity and social proof.
* You want to backtest it, activate it, observe notifications, track performance, and receive webhook events.

## Prerequisites

Set your environment variables:

```bash theme={null}
export MP_BASE_URL="https://api.memeperfect.io/api/external/v1"
export MP_API_KEY="mpk_your_api_key_here"
```

Common header:

```bash theme={null}
-H "X-API-Key: $MP_API_KEY"
```

## Step 1: Confirm plan and limits

```bash theme={null}
curl -s "$MP_BASE_URL/me" \
  -H "X-API-Key: $MP_API_KEY"
```

Use this to confirm:

* your plan (`PRO` or `DEGEN`)
* strategy activation limit
* requests-per-minute limit

## Step 2: Create a strategy

This example strategy:

* triggers on newly created tokens
* uses a single external `rules[]` list
* marks critical checks as dealbreakers
* applies market, launch-origin, volume/activity, and social filters
* sets `alertCooldownMins` to suppress duplicate alerts per token
* keeps default trigger config empty because this example does not use twitter trigger types

```bash theme={null}
curl -s -X POST "$MP_BASE_URL/strategies" \
  -H "X-API-Key: $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Safe Launch Flow",
    "description": "Programmatic strategy for safer early launches",
    "strict": true,
    "alertCooldownMins": 30,
    "triggers": ["new_token_created"],
    "rules": [
      { "rule": "is_honeypot", "dealbreaker": true, "enabled": true },
      { "rule": "has_freeze_authority", "dealbreaker": true, "enabled": true },
      { "rule": "risk_level", "dealbreaker": true, "value": "LOW" },
      { "rule": "launch_platform", "dealbreaker": false, "operator": "not_equals", "value": "pump_fun" },
      { "rule": "liquidity_usd", "dealbreaker": false, "min": 10000 },
      { "rule": "market_cap", "dealbreaker": false, "max": 1500000 },
      { "rule": "volume_24h", "dealbreaker": false, "config": { "windows": { "5m": 5000, "1h": 10000, "6h": 25000, "24h": 50000 } } },
      { "rule": "buy_sell_ratio_window", "dealbreaker": false, "config": { "window": "1h", "buyPressure": "moderate" } },
      { "rule": "quality_wallet_count", "dealbreaker": false, "config": { "minWallets": 5, "walletTypes": ["smart_wallet", "kol", "whale", "profitable_trader"] } },
      { "rule": "has_website", "dealbreaker": false, "enabled": true },
      { "rule": "has_twitter", "dealbreaker": false, "enabled": true },
      { "rule": "website_content_validation_score", "dealbreaker": false, "min": 50 }
    ],
    "matching": {
      "enabled": true,
      "minPercent": 80
    },
    "isActive": false
  }'
```

Save `strategy.id` from the response for the next steps.

## Step 3: Activate the strategy

```bash theme={null}
export MP_STRATEGY_ID="your-strategy-uuid"

curl -s -X POST "$MP_BASE_URL/strategies/$MP_STRATEGY_ID/activate" \
  -H "X-API-Key: $MP_API_KEY"
```

## Step 4: Verify strategy state

```bash theme={null}
curl -s "$MP_BASE_URL/strategies/$MP_STRATEGY_ID" \
  -H "X-API-Key: $MP_API_KEY"
```

Check:

* `isActive` is `true`
* `alertCooldownMins` is present
* response contains `dealbreakers` and grouped rules generated from your `rules[]` payload

## Step 5: Update strategy rules

Example update:

* increase liquidity threshold
* tighten cooldown window
* keep excluding Pump.fun-origin launches
* keep wallet quality checks as normal rules, not dealbreakers
* replace the full stored rules set with the new `rules[]` payload

```bash theme={null}
curl -s -X PATCH "$MP_BASE_URL/strategies/$MP_STRATEGY_ID" \
  -H "X-API-Key: $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alertCooldownMins": 45,
    "rules": [
      { "rule": "is_honeypot", "dealbreaker": true, "enabled": true },
      { "rule": "risk_level", "dealbreaker": true, "value": "LOW" },
      { "rule": "launch_platform", "dealbreaker": false, "operator": "not_equals", "value": "pump_fun" },
      { "rule": "liquidity_usd", "dealbreaker": false, "min": 15000 },
      { "rule": "quality_wallet_total_value", "dealbreaker": false, "config": { "minTotalValueUsd": 5000, "walletTypes": ["smart_wallet", "whale"] } },
      { "rule": "has_twitter", "dealbreaker": false, "enabled": true }
    ]
  }'
```

To fully clear existing rules, use replacement semantics with an empty list:

```bash theme={null}
curl -s -X PATCH "$MP_BASE_URL/strategies/$MP_STRATEGY_ID" \
  -H "X-API-Key: $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": []
  }'
```

Trigger updates follow the same replacement behavior: if you send `triggers`, the full trigger set is replaced; if omitted, existing triggers stay unchanged.

## Step 6: Optional backtest before going live

Run a backtest when you want to replay a Strategy against recent stored token observations before relying on it in production.

<Info>
  `PRO` users can run 25 backtests per UTC day with a 7-day lookback. `DEGEN`
  users have unlimited daily backtests with a 14-day lookback.
</Info>

Create a backtest job:

```bash theme={null}
curl -s -X POST "$MP_BASE_URL/backtests" \
  -H "X-API-Key: $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"strategyId\": \"$MP_STRATEGY_ID\",
    \"from\": \"2026-05-16T00:00:00.000Z\",
    \"to\": \"2026-05-23T00:00:00.000Z\",
    \"labelDefinition\": {
      \"threshold\": 2
    },
    \"options\": {
      \"eventType\": \"new_token_created\",
      \"strictOverride\": true
    }
  }"
```

Save the returned `id` as your backtest job ID, then poll job status:

```bash theme={null}
export MP_BACKTEST_ID="backtest-job-id"

curl -s "$MP_BASE_URL/backtests/$MP_BACKTEST_ID" \
  -H "X-API-Key: $MP_API_KEY"
```

List filtered results:

```bash theme={null}
curl -s "$MP_BASE_URL/backtests/$MP_BACKTEST_ID/results?page=1&pageSize=50&winnersInWindow=true&sortBy=multiple&sortDir=desc" \
  -H "X-API-Key: $MP_API_KEY"
```

Backtest results store matches and missed winners only. `currentMultiple` is calculated from the token's highest market cap during the backtest window compared with its market cap when it was evaluated, not from a live market lookup. The results `total` is the stored-row count; use the job `metrics.tested` value for the full evaluated-token count.

## Step 7: Optional twitter/dev discovery queries

Get tracked twitter handles:

```bash theme={null}
curl -s "$MP_BASE_URL/twitter/handles?status=active&sortBy=addedAt&sortOrder=desc" \
  -H "X-API-Key: $MP_API_KEY"
```

Get twitter tags (all scopes by default):

```bash theme={null}
curl -s "$MP_BASE_URL/twitter/tags?scope=all&includeCounts=true" \
  -H "X-API-Key: $MP_API_KEY"
```

Get followed developers:

```bash theme={null}
curl -s "$MP_BASE_URL/devs/my?page=1&limit=20&isActive=true" \
  -H "X-API-Key: $MP_API_KEY"
```

For twitter trigger strategies (`twitter_mention_direct` / `tweet_metadata_match`), include `triggerConfigs.<eventType>.tagId` in create/update payloads.

For followed developer strategies, use `triggerConfigs.followed_dev_new_token_created` to choose the source:

```json theme={null}
{
  "scope": "all"
}
```

```json theme={null}
{
  "scope": "tag",
  "tagId": "dev-tag-uuid-from-devs-tags"
}
```

```json theme={null}
{
  "scope": "wallet",
  "developerAddress": "followed-dev-wallet-address"
}
```

If you omit this config, `followed_dev_new_token_created` uses all active followed developers.

## Step 8: Read notifications programmatically

List recent notifications:

```bash theme={null}
curl -s "$MP_BASE_URL/notifications?page=1&limit=20&strategyId=$MP_STRATEGY_ID" \
  -H "X-API-Key: $MP_API_KEY"
```

Notifications default to `source=all`, which returns your personal alerts plus official alerts from official strategies you are subscribed to. Use `source=personal` or `source=official` to narrow the result. Each notification item includes `source` so clients can tell which kind of alert it is.

Read one notification in detail:

```bash theme={null}
export MP_NOTIFICATION_ID="your-notification-uuid"

curl -s "$MP_BASE_URL/notifications/$MP_NOTIFICATION_ID" \
  -H "X-API-Key: $MP_API_KEY"
```

## Step 9: Check performance

Synchronous summary:

```bash theme={null}
curl -s "$MP_BASE_URL/notifications/performance?range=daily&strategyId=$MP_STRATEGY_ID" \
  -H "X-API-Key: $MP_API_KEY"
```

Asynchronous flow for larger workloads:

```bash theme={null}
curl -s -X POST "$MP_BASE_URL/notifications/performance/jobs?range=daily&strategyId=$MP_STRATEGY_ID" \
  -H "X-API-Key: $MP_API_KEY"
```

Then poll:

```bash theme={null}
export MP_JOB_ID="job-id-from-previous-response"

curl -s "$MP_BASE_URL/notifications/performance/jobs/$MP_JOB_ID" \
  -H "X-API-Key: $MP_API_KEY"
```

## Step 10: Configure webhook delivery

Check current config:

```bash theme={null}
curl -s "$MP_BASE_URL/webhook" \
  -H "X-API-Key: $MP_API_KEY"
```

Set webhook endpoint:

```bash theme={null}
curl -s -X PUT "$MP_BASE_URL/webhook" \
  -H "X-API-Key: $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url": "https://your-domain.com/memeperfect/webhook"
  }'
```

Use returned fields:

* `hasSecret`
* `secret` (when generated/rotated)
* `verifiedAt`
* `verificationError` (if verification failed)

## Step 11: Deactivate strategy

```bash theme={null}
curl -s -X POST "$MP_BASE_URL/strategies/$MP_STRATEGY_ID/deactivate" \
  -H "X-API-Key: $MP_API_KEY"
```

## Step 12: Optional cleanup

```bash theme={null}
curl -s -X DELETE "$MP_BASE_URL/strategies/$MP_STRATEGY_ID" \
  -H "X-API-Key: $MP_API_KEY"
```

## Practical implementation checklist

* Keep API key server-side only.
* Persist strategy IDs in your own DB.
* Use idempotent update logic in your integration.
* Handle `429` throttling with retry/backoff.
* Validate rule payloads with the [Strategy Rules Spec](/developers/strategy-rules) before sending.

<CardGroup cols={2}>
  <Card title="APIs" icon="code" href="/developers/apis">
    Full endpoint reference and payload examples.
  </Card>

  <Card title="Strategy Rules Spec" icon="list-check" href="/developers/strategy-rules">
    Rule schema, operators, and supported rule types.
  </Card>
</CardGroup>