Skip to main content
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

Base URL

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

Getting an API key

  1. Open Settings in the app.
  2. Go to API Access.
Developer API key generation screen
  1. Create or regenerate your API key.
Generated API key shown in the dashboard
  1. 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
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:
  1. GET /me
  2. POST /strategies
  3. POST /strategies/:id/activate
  4. GET /notifications and GET /notifications/:id
  5. GET /notifications/performance or async performance jobs
  6. PUT /webhook
  7. 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)
Rules are sent as one flat list and remapped internally into:
  • dealbreakers
  • rule groups (Security, Market, Socials, 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: currently risk_level)
Optional trigger config map (required for twitter trigger types):
  • triggerConfigs.twitter_mention_direct.tagId
  • triggerConfigs.tweet_metadata_match.tagId
  • triggerConfigs.followed_dev_new_token_created (optional; supports scoped followed-dev trigger config)
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": "liquidity_usd", "dealbreaker": false, "min": 10000 },
      { "rule": "market_cap", "dealbreaker": false, "max": 1500000 },
      { "rule": "has_twitter", "dealbreaker": false, "enabled": true }
    ],
    "isActive": false
  }'
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
  }'
Response still returns internal dealbreakers and ruleGroups. Those are generated from your external 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, backend remaps and fully replaces internal dealbreakers and ruleGroups.
  • If rules is explicitly [], backend clears internal dealbreakers and ruleGroups.
  • If triggers is included, backend fully replaces internal 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 /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)
  • strategyId (optional)
  • triggerType (optional)
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",
      "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.
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",
  "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.