APIs - MemePerfect Docs

Use this page to integrate directly with MemePerfect’s external API. If you are integrating for the first time, start with the end-to-end API Walkthrough, then use this page as endpoint reference.

Illustration for developer API key section — Use the external API to manage Strategies and consume alert outcomes from your own systems.

Base URL

https://api.memeperfect.io/api/external/v1

Getting an API key

Open Settings in the app.
Go to API Access.

Developer API key generation screen — Generate your API key from Settings.

Create or regenerate your API key.

Generated API key shown in the dashboard — The full key is only shown at generation time.

Store it securely.

Never expose API keys in browser code or public repositories.

Authentication

The API accepts one of these header formats:

X-API-Key: mpk_your_api_key_here

Authorization: ApiKey mpk_your_api_key_here

X-MP-API-Key is not accepted. Use X-API-Key or Authorization: ApiKey ....

Rate limits and plan limits

Limits are plan-based and enforced per API key:

PRO: 60 requests per minute, up to 25 active Strategies
DEGEN: 300 requests per minute, up to 50 active Strategies
Backtests: PRO gets 25 jobs per UTC day with a 7-day lookback; DEGEN gets unlimited daily jobs with a 14-day lookback

Check current limits with GET /me.

Common error shape

Validation and auth errors use this structure:

{
  "statusCode": 401,
  "message": "API key required. Provide via X-API-Key header or Authorization: ApiKey <key>",
  "error": "Unauthorized"
}

Endpoint reference

Lifecycle order:

GET /me
POST /strategies
POST /strategies/:id/activate
GET /strategy-evaluations
POST /backtests and GET /backtests/:id/results
GET /notifications and GET /notifications/:id
GET /notifications/performance or async performance jobs
PUT /webhook
POST /strategies/:id/deactivate

`GET /me`

Returns authenticated user plan and limits.

curl -X GET 'https://api.memeperfect.io/api/external/v1/me' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "userId": "4fcb13dc-2f0c-49bb-97a3-2f2f7ac0f80f",
  "plan": "PRO",
  "limits": {
    "strategies": {
      "total": null,
      "active": 25
    },
    "rateLimit": {
      "requestsPerMinute": 60
    }
  }
}

`GET /strategies`

Returns all Strategies for the authenticated user and activeCount.

curl -X GET 'https://api.memeperfect.io/api/external/v1/strategies' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "strategies": [
    {
      "id": "b1b3f6f3-84be-4c7c-8e44-4cb4a58bad55",
      "name": "Momentum Strategy",
      "description": "Filters for high social acceleration",
      "userId": "4fcb13dc-2f0c-49bb-97a3-2f2f7ac0f80f",
      "triggers": [
        {
          "id": "t1",
          "eventType": "new_token_created",
          "enabled": true
        }
      ],
      "dealbreakers": [],
      "ruleGroups": [
        {
          "id": "security",
          "name": "Security",
          "logic": "AND",
          "rules": []
        },
        {
          "id": "market",
          "name": "Market",
          "logic": "AND",
          "rules": []
        },
        {
          "id": "socials",
          "name": "Socials",
          "logic": "AND",
          "rules": []
        },
        {
          "id": "ai",
          "name": "AI",
          "logic": "AND",
          "rules": []
        }
      ],
      "strict": false,
      "alertCooldownMins": 30,
      "isActive": true,
      "isGlobal": false,
      "matching": {
        "enabled": true,
        "minPercent": 80
      },
      "createdAt": "2026-03-09T08:22:11.318Z",
      "updatedAt": "2026-03-09T08:22:11.318Z"
    }
  ],
  "activeCount": 1
}

`POST /strategies`

Creates a new Strategy. Required body fields:

name (string)
triggers (array)
rules (array)
isActive (boolean)

Send rules as one flat list. MemePerfect organizes them into:

dealbreakers
product rule groups such as Security, Market, Volume/Activity, Clusters, Socials, and AI

Rule item shape:

rule (string, required)
dealbreaker (boolean, required)
enabled (boolean, optional. enabled: false skips any rule type)
min / max (number, numeric rules only)
value (string, enum rules only: risk_level, launch_platform)
operator (string, enum rules only: equals or not_equals; defaults to equals)
config (object, advanced market, volume/activity, and wallet-quality rules only)
clusterConfig (object, coordinated wallet cluster rules only)

Advanced rule examples:

{ "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": "validated_volume_spike", "dealbreaker": false, "config": { "window": "5m", "volumeSpike": "very_strong" } }

{ "rule": "quality_wallet_count", "dealbreaker": false, "config": { "minWallets": 5, "walletTypes": ["smart_wallet", "kol", "whale", "profitable_trader"] } }

{ "rule": "quality_wallet_total_value", "dealbreaker": false, "config": { "minTotalValueUsd": 5000, "walletTypes": ["smart_wallet", "whale"] } }

{ "rule": "quality_wallet_min_winrate", "dealbreaker": false, "config": { "minWinratePct": 60, "minWalletsAboveThreshold": 3, "walletTypes": ["smart_wallet", "profitable_trader"] } }

{ "rule": "coordinated_wallet_cluster", "dealbreaker": false, "clusterConfig": { "maxTotalHeldPct": 20, "maxSingleClusterPct": 10, "maxClusterRisk": "high" } }

These rules cannot be submitted as dealbreakers:

Website Shows CA
Website Contains $Token Name
Website Content Validity Score
X Link Contains CA
X Link Contains $Token Name
X Views
X Followers
X Community Size
X Community Views
X (Twitter) Content Validity Score
Coordinated Wallet Cluster
Quality Wallets
Quality Wallet Buy Value
Quality Wallet Win Rate

Optional trigger config map:

triggerConfigs.twitter_mention_direct.tagId is required for twitter_mention_direct; use "all" or a Twitter tag id.
triggerConfigs.tweet_metadata_match.tagId is required for tweet_metadata_match; use "all" or a Twitter tag id.
triggerConfigs.followed_dev_new_token_created.scope is optional and accepts "all", "tag", or "wallet".
triggerConfigs.followed_dev_new_token_created.tagId is required when scope is "tag"; use a dev tag id from GET /devs/tags.
triggerConfigs.followed_dev_new_token_created.developerAddress is required when scope is "wallet"; the wallet must be in your followed developers list.

If triggerConfigs.followed_dev_new_token_created is omitted, the followed-dev trigger behaves as scope: "all". Important strategy-level options:

strict (optional, boolean)
alertCooldownMins (optional, number 0 to 1440)

Allowed trigger eventType values:

new_token_created
followed_dev_new_token_created
twitter_mention_direct
tweet_metadata_match
token_almost_graduated
token_graduated

curl -X POST 'https://api.memeperfect.io/api/external/v1/strategies' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "E2E Test Strategy",
    "strict": true,
    "alertCooldownMins": 30,
    "triggers": ["new_token_created"],
    "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": 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_twitter", "dealbreaker": false, "enabled": true }
    ],
    "isActive": false
  }'

Followed developer trigger examples:

curl -X POST 'https://api.memeperfect.io/api/external/v1/strategies' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "All followed dev launches",
    "triggers": ["followed_dev_new_token_created"],
    "triggerConfigs": {
      "followed_dev_new_token_created": {
        "scope": "all"
      }
    },
    "rules": [
      { "rule": "is_honeypot", "dealbreaker": true, "enabled": true },
      { "rule": "liquidity_usd", "dealbreaker": false, "min": 10000 }
    ],
    "isActive": true
  }'

{
  "triggers": ["followed_dev_new_token_created"],
  "triggerConfigs": {
    "followed_dev_new_token_created": {
      "scope": "tag",
      "tagId": "b0d6a1d8-6e6c-4f80-9a61-5b8a3c4b2a11"
    }
  }
}

{
  "triggers": ["followed_dev_new_token_created"],
  "triggerConfigs": {
    "followed_dev_new_token_created": {
      "scope": "wallet",
      "developerAddress": "7xKXExampleDeveloperWallet"
    }
  }
}

Twitter trigger example:

curl -X POST 'https://api.memeperfect.io/api/external/v1/strategies' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Twitter mentions by tag",
    "triggers": ["twitter_mention_direct"],
    "triggerConfigs": {
      "twitter_mention_direct": {
        "tagId": "all"
      }
    },
    "rules": [
      { "rule": "is_honeypot", "dealbreaker": true, "enabled": true },
      { "rule": "liquidity_usd", "dealbreaker": false, "min": 10000 }
    ],
    "isActive": true
  }'

The response may include dealbreakers and ruleGroups; these are generated from your rules[] payload.

{
  "strategy": {
    "id": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
    "name": "E2E Test Strategy",
    "description": null,
    "userId": "4fcb13dc-2f0c-49bb-97a3-2f2f7ac0f80f",
    "triggers": [
      {
        "id": "t1",
        "eventType": "new_token_created",
        "enabled": true
      }
    ],
    "dealbreakers": [
      {
        "id": "d1f6f6fe-b6e7-4f65-a5ed-4cddf0f20274",
        "ruleType": "is_honeypot",
        "operator": "is",
        "value": false,
        "enabled": true
      },
      {
        "id": "4155b2c2-6459-4b09-a406-f6f45887ef4a",
        "ruleType": "risk_level",
        "operator": "equals",
        "value": "LOW",
        "enabled": true
      }
    ],
    "ruleGroups": [
      {
        "id": "b9793be5-2667-4d64-9d03-e8f89b022f75",
        "name": "Market",
        "logic": "AND",
        "rules": [
          {
            "id": "ad59ec06-4f8b-490e-a7f6-78de34a37834",
            "ruleType": "liquidity_usd",
            "operator": "greater_than",
            "value": 10000,
            "enabled": true
          },
          {
            "id": "95f08d8c-fb80-4c7f-a1ce-85ce6bb005ca",
            "ruleType": "market_cap",
            "operator": "less_than",
            "value": 1500000,
            "enabled": true
          }
        ]
      },
      {
        "id": "d967eeb9-b7d0-4aaf-a84a-45b378e56f2d",
        "name": "Socials",
        "logic": "AND",
        "rules": [
          {
            "id": "6d04ecb7-650c-4c66-94e6-0f4dd44bc45d",
            "ruleType": "has_twitter",
            "operator": "is",
            "value": true,
            "enabled": true
          }
        ]
      }
    ],
    "strict": true,
    "alertCooldownMins": 30,
    "isActive": false,
    "isGlobal": false,
    "createdAt": "2026-03-09T08:25:58.221Z",
    "updatedAt": "2026-03-09T08:25:58.221Z"
  }
}

`GET /strategies/:id`

Returns one Strategy by UUID.

curl -X GET 'https://api.memeperfect.io/api/external/v1/strategies/9a46ddf3-98fd-4cf5-8fd0-022421741c35' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "strategy": {
    "id": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
    "name": "E2E Test Strategy",
    "description": null,
    "userId": "4fcb13dc-2f0c-49bb-97a3-2f2f7ac0f80f",
    "triggers": [
      {
        "id": "t1",
        "eventType": "new_token_created",
        "enabled": true
      }
    ],
    "dealbreakers": [
      {
        "id": "d1f6f6fe-b6e7-4f65-a5ed-4cddf0f20274",
        "ruleType": "is_honeypot",
        "operator": "is",
        "value": false,
        "enabled": true
      },
      {
        "id": "4155b2c2-6459-4b09-a406-f6f45887ef4a",
        "ruleType": "risk_level",
        "operator": "equals",
        "value": "LOW",
        "enabled": true
      }
    ],
    "ruleGroups": [
      {
        "id": "b9793be5-2667-4d64-9d03-e8f89b022f75",
        "name": "Market",
        "logic": "AND",
        "rules": [
          {
            "id": "ad59ec06-4f8b-490e-a7f6-78de34a37834",
            "ruleType": "liquidity_usd",
            "operator": "greater_than",
            "value": 10000,
            "enabled": true
          },
          {
            "id": "95f08d8c-fb80-4c7f-a1ce-85ce6bb005ca",
            "ruleType": "market_cap",
            "operator": "less_than",
            "value": 1500000,
            "enabled": true
          }
        ]
      },
      {
        "id": "d967eeb9-b7d0-4aaf-a84a-45b378e56f2d",
        "name": "Socials",
        "logic": "AND",
        "rules": [
          {
            "id": "6d04ecb7-650c-4c66-94e6-0f4dd44bc45d",
            "ruleType": "has_twitter",
            "operator": "is",
            "value": true,
            "enabled": true
          }
        ]
      }
    ],
    "strict": true,
    "alertCooldownMins": 30,
    "isActive": false,
    "createdAt": "2026-03-09T08:25:58.221Z",
    "updatedAt": "2026-03-09T08:25:58.221Z"
  }
}

`PATCH /strategies/:id`

Partially updates a Strategy. Uses the same schema as POST /strategies, but all fields are optional. Replacement semantics:

If rules is included, MemePerfect fully replaces the strategy’s saved rules.
If rules is explicitly [], MemePerfect clears the strategy’s saved rules.
If triggers is included, MemePerfect fully replaces the strategy’s saved triggers.
If rules or triggers are omitted, existing values remain unchanged.

curl -X PATCH 'https://api.memeperfect.io/api/external/v1/strategies/9a46ddf3-98fd-4cf5-8fd0-022421741c35' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated E2E Strategy",
    "description": "Updated desc"
  }'

{
  "strategy": {
    "id": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
    "name": "Updated E2E Strategy",
    "description": "Updated desc",
    "isActive": false
  }
}

Clear all rules example:

curl -X PATCH 'https://api.memeperfect.io/api/external/v1/strategies/9a46ddf3-98fd-4cf5-8fd0-022421741c35' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "rules": []
  }'

`POST /strategies/:id/activate`

Activates a Strategy.

curl -X POST 'https://api.memeperfect.io/api/external/v1/strategies/9a46ddf3-98fd-4cf5-8fd0-022421741c35/activate' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "strategy": {
    "id": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
    "isActive": true
  }
}

`POST /strategies/:id/deactivate`

Deactivates a Strategy.

curl -X POST 'https://api.memeperfect.io/api/external/v1/strategies/9a46ddf3-98fd-4cf5-8fd0-022421741c35/deactivate' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "strategy": {
    "id": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
    "isActive": false
  }
}

`DELETE /strategies/:id`

Deletes a Strategy.

curl -X DELETE 'https://api.memeperfect.io/api/external/v1/strategies/9a46ddf3-98fd-4cf5-8fd0-022421741c35' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "success": true
}

`GET /strategy-evaluations`

Lists persisted Strategy evaluation snapshots for the authenticated user. Use this to review matched and failed evaluations without calling the current market-cap, ATH, or performance endpoints.

This endpoint is optimized for recent evaluation history. Prefer hasMore and nextCursor for pagination. The exact total is returned as null.

Evaluation history only returns records from the last day. The from filter is limited to that retention window.

Query parameters:

page (optional, default 1; used when cursor is not provided)
pageSize (optional, default 50, max 100)
limit (optional alias for pageSize; pageSize wins when both are sent)
cursor (optional opaque value returned as nextCursor; use with the same filters and sort)
sortBy (createdAt | matched | evaluationTimeMs | tokenAddress | strategyId | mcap | liquidity, optional)
sortDir (asc | desc, optional)
matched (true | false, optional)
strategyId (Strategy UUID, optional)
address (token address exact match, or partial match when % is present, optional)
datetime (ISO datetime one-minute window, or YYYY-MM-DD UTC day window, optional)
dealbreakerFailed (true | false, optional)
failedGroupIds (CSV or repeated query parameter; matches exactly that failed-group set, optional)
from / to (strict ISO 8601 createdAt bounds, optional; from must be before or equal to to)

curl -X GET 'https://api.memeperfect.io/api/external/v1/strategy-evaluations?page=1&matched=true&sortBy=createdAt&sortDir=desc' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "items": [
    {
      "evaluationId": "79a42f9c-2338-4835-bddc-4137a42ca678",
      "strategyId": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
      "strategyName": "E2E Test Strategy",
      "userId": "4fcb13dc-2f0c-49bb-97a3-2f2f7ac0f80f",
      "tokenAddress": "So11111111111111111111111111111111111111112",
      "eventType": "new_token_created",
      "matched": true,
      "matchDetails": {
        "matchedGroups": ["market"]
      },
      "failedRules": [],
      "baselineAt": "2026-05-07T10:00:00.000Z",
      "baselinePrice": 0.001,
      "baselineMcap": 100000,
      "failureReason": null,
      "marketAtEval": {
        "liquidityUsd": 25000
      },
      "riskAtEval": {
        "riskLevel": "LOW"
      },
      "sourceContext": {
        "source": "realtime"
      },
      "createdAt": "2026-05-07T10:00:00.000Z",
      "debugTrail": []
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": null,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJzb3J0QnkiOiJjcmVhdGVkQXQiLCJzb3J0RGlyIjoiREVTQyIsImlkIjoiNzlhNDJmOWMtMjMzOC00ODM1LWJkZGMtNDEzN2E0MmNhNjc4In0"
}

This endpoint returns stored evaluation state only. It does not include currentMcap, athPrice, athMcap, athAt, currentMultiple, or athMultiple, and it does not expose /mcaps, /performance, or /analyze under the external Strategy Evaluations API. To fetch the next page, pass the previous response’s nextCursor with the same filters and sort:

curl -X GET 'https://api.memeperfect.io/api/external/v1/strategy-evaluations?pageSize=50&cursor=NEXT_CURSOR_FROM_PREVIOUS_RESPONSE&matched=true&sortBy=createdAt&sortDir=desc' \
  -H 'X-API-Key: YOUR_API_KEY'

`GET /backtests`

Lists async backtest jobs for the authenticated user. Query parameters:

page (optional, default 1; fixed page size 20)

curl -X GET 'https://api.memeperfect.io/api/external/v1/backtests?page=1' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "items": [
    {
      "id": "39bcdd52-7e7e-4854-a3d7-b49c59b6fd21",
      "status": "COMPLETED",
      "strategyId": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
      "strategyName": "E2E Test Strategy",
      "from": "2026-05-16T00:00:00.000Z",
      "to": "2026-05-23T00:00:00.000Z",
      "labelDefinition": {
        "threshold": 2
      },
      "options": {
        "eventType": "new_token_created",
        "strictOverride": true
      },
      "metrics": {
        "tested": 240,
        "positives": 18,
        "winnersNow": 6,
        "precision": 0.33,
        "recall": 1,
        "f1": 0.5
      },
      "createdAt": "2026-05-23T10:15:00.000Z",
      "updatedAt": "2026-05-23T10:17:40.000Z",
      "error": null
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1,
  "hasMore": false
}

metrics.winnersNow is retained for response compatibility. For disk-backed backtests it represents winners inside the effective snapshot window, not a live market lookup.

`POST /backtests`

Queues a backtest job for one of your Strategies. The API stores a strategy snapshot when the job is created, so later edits to the live Strategy do not change that backtest run. Backtests replay hourly disk snapshots built from completed UTC hours. If your requested window overlaps available snapshot coverage, the returned job from and to are clamped to the available slice. If there is no overlap, the API returns 400 with the available range.

PRO users can create 25 backtests per UTC day with a 7-day lookback. DEGEN users have unlimited daily backtests with a 14-day lookback.

Required body fields:

strategyId (Strategy UUID owned by the API-key user)
from / to (ISO 8601 datetimes)
labelDefinition.threshold (number; snapshot-window winner multiple threshold)
options (object; send {} when you do not need options)

Optional options fields:

eventType (string)
strictOverride (boolean)

curl -X POST 'https://api.memeperfect.io/api/external/v1/backtests' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "strategyId": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
    "from": "2026-05-16T00:00:00.000Z",
    "to": "2026-05-23T00:00:00.000Z",
    "labelDefinition": {
      "threshold": 2
    },
    "options": {
      "eventType": "new_token_created",
      "strictOverride": true
    }
  }'

{
  "id": "39bcdd52-7e7e-4854-a3d7-b49c59b6fd21",
  "status": "QUEUED",
  "strategyId": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
  "from": "2026-05-16T00:00:00.000Z",
  "to": "2026-05-23T00:00:00.000Z",
  "labelDefinition": {
    "threshold": 2
  },
  "options": {
    "eventType": "new_token_created",
    "strictOverride": true
  }
}

`GET /backtests/:id`

Returns one backtest job owned by the authenticated user.

curl -X GET 'https://api.memeperfect.io/api/external/v1/backtests/39bcdd52-7e7e-4854-a3d7-b49c59b6fd21' \
  -H 'X-API-Key: YOUR_API_KEY'

Missing or cross-user backtest IDs return 404.

`GET /backtests/:id/results`

Returns paginated stored backtest result rows plus todayCount. Backtest results store matches and missed winners only:

matched tokens, including true positives and false positives
non-matched tokens whose snapshot-window currentMultiple reaches the threshold, meaning missed winners

Non-matched non-winners are counted in job metrics but are not stored as result rows. The response total is the stored-row count after filters; use the job metrics.tested field for the full evaluated-token count. Query parameters:

page (optional, default 1)
pageSize (optional, default 50, max 200)
matched (true | false | all, optional)
winnersInWindow (true | false | all, optional; preferred)
winnersNow (true | false | all, optional; backward-compatible alias for winnersInWindow)
minMultiple / maxMultiple (optional)
token (optional token-address search)
sortBy (evaluationTimestamp | multiple | matched, optional)
sortDir (asc | desc, optional)

sortBy=multiple, minMultiple, maxMultiple, winnersInWindow, and winnersNow use currentMultiple, which is calculated from the token’s highest market cap during the backtest window compared with its market cap when it was evaluated. It is not a live Birdeye multiple.

curl -X GET 'https://api.memeperfect.io/api/external/v1/backtests/39bcdd52-7e7e-4854-a3d7-b49c59b6fd21/results?page=1&pageSize=50&winnersInWindow=true&sortBy=multiple&sortDir=desc' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "items": [
    {
      "id": "b83abde1-a2b7-4d21-8188-7e819f61dfd9",
      "jobId": "39bcdd52-7e7e-4854-a3d7-b49c59b6fd21",
      "tokenAddress": "So11111111111111111111111111111111111111112",
      "evaluationTimestamp": "2026-05-22T14:02:00.000Z",
      "matched": true,
      "currentMultiple": 2.4,
      "multiples": {
        "0": 2.4
      },
      "mcaps": {
        "0": 240000
      },
      "matchDetails": {},
      "snapshot": {
        "createdAt": "2026-05-22T14:02:00.000Z",
        "strategyId": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
        "strategyName": "E2E Test Strategy",
        "matched": true,
        "failureReason": null
      }
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "hasMore": false,
  "todayCount": 3
}

`GET /twitter/handles`

Read-only list of tracked Twitter handles for the authenticated user. Query parameters:

search (optional)
tagId (optional)
status (active | inactive, optional)
sortBy (handle | addedAt | lastUpdated, optional)
sortOrder (asc | desc, optional)

curl -X GET 'https://api.memeperfect.io/api/external/v1/twitter/handles?status=active&sortBy=addedAt&sortOrder=desc' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "handles": [
    {
      "id": "9a2e931b-c70f-4cde-aeac-15b7f2f7df91",
      "handle": "@alpha",
      "status": "active",
      "tags": [
        { "id": "40153fe3-a61a-4e8f-868f-fd6bdccfd6b2", "name": "Smart money" }
      ],
      "addedAt": "2026-03-11T10:00:00.000Z",
      "lastUpdated": "2026-03-11T10:00:00.000Z"
    }
  ]
}

`GET /twitter/tags`

Read-only Twitter tags. Returns both user and platform tags by default. Query parameters:

scope (all | user | platform, default all)
includeCounts (boolean, default true)
sortBy (name | createdAt | handleCount, default name)
sortOrder (asc | desc, default asc)

curl -X GET 'https://api.memeperfect.io/api/external/v1/twitter/tags?scope=all&includeCounts=true' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "tags": [
    {
      "id": "40153fe3-a61a-4e8f-868f-fd6bdccfd6b2",
      "name": "Smart money",
      "isPlatformTag": false,
      "handleCount": 12
    }
  ]
}

`GET /devs/my`

Lists your followed developers. Query parameters:

page (optional, default 1)
limit (optional, default 20)
isActive (optional)

curl -X GET 'https://api.memeperfect.io/api/external/v1/devs/my?page=1&limit=20&isActive=true' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "developers": [],
  "total": 0,
  "page": 1,
  "totalPages": 0,
  "activeCount": 0
}

`GET /devs/tags`

Returns your developer tags.

curl -X GET 'https://api.memeperfect.io/api/external/v1/devs/tags' \
  -H 'X-API-Key: YOUR_API_KEY'

`GET /devs/:address/tags`

Returns tag IDs currently assigned to a followed dev wallet.

curl -X GET 'https://api.memeperfect.io/api/external/v1/devs/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/tags' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "tagIds": ["b0d6a1d8-6e6c-4f80-9a61-5b8a3c4b2a11"]
}

`POST /devs/:address/add`

Adds a wallet to your followed developers list.

curl -X POST 'https://api.memeperfect.io/api/external/v1/devs/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/add' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "alias": "High conviction dev"
  }'

`PUT /devs/:address/update`

Updates alias and/or active status for a followed dev wallet.

curl -X PUT 'https://api.memeperfect.io/api/external/v1/devs/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/update' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "alias": "Updated alias",
    "isActive": true
  }'

`PUT /devs/:address/tags`

Replaces assigned tag IDs for a followed dev wallet.

curl -X PUT 'https://api.memeperfect.io/api/external/v1/devs/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/tags' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tagIds": ["b0d6a1d8-6e6c-4f80-9a61-5b8a3c4b2a11"]
  }'

`GET /notifications`

Lists notifications with pagination and optional filtering. Query parameters:

page (optional, default 1)
limit (optional, default 20, max 100)
source (optional, default all; allowed: all, personal, official)
strategyId (optional)
triggerType (optional)

By default, this endpoint returns both personal alerts and official alerts from official strategies you are subscribed to. Use source=personal or source=official when you want only one alert source.

curl -X GET 'https://api.memeperfect.io/api/external/v1/notifications?page=1&limit=20&strategyId=9a46ddf3-98fd-4cf5-8fd0-022421741c35' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "items": [
    {
      "id": "497e3b40-3a6e-449f-87cd-4f96af15cffe",
      "source": "personal",
      "audienceType": "personal",
      "userId": "4fcb13dc-2f0c-49bb-97a3-2f2f7ac0f80f",
      "strategyId": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
      "channel": "telegram",
      "status": "sent",
      "triggerEventType": "new_token_created",
      "triggerContext": {
        "tokenAddress": "7xKXExampleAddress",
        "tokenData": {
          "tokenSymbol": "EXAMPLE",
          "market": {
            "priceUSD": 0.00012,
            "mcap": 120000
          }
        }
      },
      "sentAt": "2026-03-09T08:31:05.120Z",
      "createdAt": "2026-03-09T08:31:05.120Z",
      "updatedAt": "2026-03-09T08:31:05.120Z",
      "strategy": {
        "id": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
        "name": "Updated E2E Strategy"
      }
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1,
  "totalPages": 1
}

`GET /notifications/:id`

Returns one notification for the authenticated user, including live performance snapshot. Query parameters:

source (optional, default all; allowed: all, personal, official)
view (optional, default full; allowed: full, summary)

curl -X GET 'https://api.memeperfect.io/api/external/v1/notifications/497e3b40-3a6e-449f-87cd-4f96af15cffe' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "id": "497e3b40-3a6e-449f-87cd-4f96af15cffe",
  "source": "personal",
  "audienceType": "personal",
  "userId": "4fcb13dc-2f0c-49bb-97a3-2f2f7ac0f80f",
  "strategyId": "9a46ddf3-98fd-4cf5-8fd0-022421741c35",
  "channel": "telegram",
  "status": "sent",
  "triggerEventType": "new_token_created",
  "triggerContext": {
    "tokenAddress": "7xKXExampleAddress"
  },
  "livePerformance": {
    "priceNow": 0.00018,
    "marketCapNow": 180000,
    "peakPrice": 0.00029,
    "athPrice": 0.00029
  },
  "sentAt": "2026-03-09T08:31:05.120Z",
  "createdAt": "2026-03-09T08:31:05.120Z",
  "updatedAt": "2026-03-09T08:31:05.120Z"
}

`GET /notifications/performance`

Returns performance summary for one Strategy and one range. Required query parameters:

strategyId (string)
range (daily | weekly | monthly | quarterly)

curl -X GET 'https://api.memeperfect.io/api/external/v1/notifications/performance?range=daily&strategyId=9a46ddf3-98fd-4cf5-8fd0-022421741c35' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "overall": {
    "totalCalls": 32,
    "winners": 9,
    "winRate": 0.28125,
    "avgAthMultiple": 1.7412,
    "bestAthMultiple": 6.2031
  },
  "buckets": [
    { "label": "<1x", "min": 0, "max": 1, "count": 10 },
    { "label": "1-1.2x", "min": 1, "max": 1.2, "count": 7 },
    { "label": "1.2-2x", "min": 1.2, "max": 2, "count": 9 },
    { "label": "2-5x", "min": 2, "max": 5, "count": 5 },
    { "label": "5-10x", "min": 5, "max": 10, "count": 1 },
    { "label": "10x+", "min": 10, "max": null, "count": 0 }
  ],
  "topTokens": [
    {
      "tokenAddress": "7xKXExampleAddress",
      "tokenSymbol": "EXAMPLE",
      "tokenName": "Example Token",
      "alertMcap": 120000,
      "currentMcap": 180000,
      "athMcap": 744372,
      "athMultiple": 6.2031
    }
  ]
}

`POST /notifications/performance/jobs`

Creates an async performance job. Required query parameters:

strategyId (string)
range (daily | weekly | monthly | quarterly)

curl -X POST 'https://api.memeperfect.io/api/external/v1/notifications/performance/jobs?range=daily&strategyId=9a46ddf3-98fd-4cf5-8fd0-022421741c35' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "jobId": "48112"
}

`GET /notifications/performance/jobs/:jobId`

Returns async performance job status and result when completed.

curl -X GET 'https://api.memeperfect.io/api/external/v1/notifications/performance/jobs/48112' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "jobId": "48112",
  "status": "active",
  "rawState": "active",
  "progress": {
    "totalTokens": 200,
    "processedTokens": 58,
    "remainingTokens": 142,
    "progressPercent": 29
  }
}

When status is completed, the response includes:

result.overall
result.buckets
result.topTokens

`GET /webhook`

Returns webhook configuration for the authenticated user.

curl -X GET 'https://api.memeperfect.io/api/external/v1/webhook' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "enabled": true,
  "url": "https://example.com/memeperfect/webhook",
  "verifiedAt": "2026-03-09T08:36:21.522Z",
  "hasSecret": true
}

`PUT /webhook`

Updates webhook configuration. Body fields:

enabled (required, boolean)
url (optional, string or null)

Behavior notes:

Set url to null to clear webhook config and secret.
When URL changes, backend attempts verification and may return verificationError.
A new secret is only returned when generated or rotated.

curl -X PUT 'https://api.memeperfect.io/api/external/v1/webhook' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "url": "https://example.com/memeperfect/webhook"
  }'

{
  "enabled": true,
  "url": "https://example.com/memeperfect/webhook",
  "verifiedAt": "2026-03-09T08:36:21.522Z",
  "hasSecret": true,
  "secret": "whsec_9SNQ...",
  "verificationError": null
}

Error cases to handle

Your client should handle at least these responses:

400 validation errors (invalid body, query, or path params)
401 missing or invalid API key
403 no active subscription or plan limit reached
404 resource not found (or belongs to another user)
429 throttled (Rate limit exceeded)

API Walkthrough

Full integration flow from create to activate, observe, webhook, and deactivate.

Webhooks

Webhook payload format, signing, and verification flow.

Strategy Rules Spec

Rule payload schema, supported ruleType IDs, operators, and value formats.

AI Agent

Build agent workflows on top of Strategy and notification outputs.

​Base URL

​Getting an API key

​Authentication

​Rate limits and plan limits

​Common error shape

​Endpoint reference

​GET /me

​GET /strategies

​POST /strategies

​GET /strategies/:id

​PATCH /strategies/:id

​POST /strategies/:id/activate

​POST /strategies/:id/deactivate

​DELETE /strategies/:id

​GET /strategy-evaluations

​GET /backtests

​POST /backtests

​GET /backtests/:id

​GET /backtests/:id/results

​GET /twitter/handles

​GET /twitter/tags

​GET /devs/my

​GET /devs/tags

​GET /devs/:address/tags

​POST /devs/:address/add

​PUT /devs/:address/update

​PUT /devs/:address/tags

​GET /notifications

​GET /notifications/:id

​GET /notifications/performance

​POST /notifications/performance/jobs

​GET /notifications/performance/jobs/:jobId

​GET /webhook

​PUT /webhook

​Error cases to handle

API Walkthrough

Webhooks

Strategy Rules Spec

AI Agent

Base URL

Getting an API key

Authentication

Rate limits and plan limits

Common error shape

Endpoint reference

`GET /me`

`GET /strategies`

`POST /strategies`

`GET /strategies/:id`

`PATCH /strategies/:id`

`POST /strategies/:id/activate`

`POST /strategies/:id/deactivate`

`DELETE /strategies/:id`

`GET /strategy-evaluations`

`GET /backtests`

`POST /backtests`

`GET /backtests/:id`

`GET /backtests/:id/results`

`GET /twitter/handles`

`GET /twitter/tags`

`GET /devs/my`

`GET /devs/tags`

`GET /devs/:address/tags`

`POST /devs/:address/add`

`PUT /devs/:address/update`

`PUT /devs/:address/tags`

`GET /notifications`

`GET /notifications/:id`

`GET /notifications/performance`

`POST /notifications/performance/jobs`

`GET /notifications/performance/jobs/:jobId`

`GET /webhook`

`PUT /webhook`

Error cases to handle