Skip to main content

​
External IDs

External IDs let you attach your app’s internal user identifiers to Clicker profiles. This means you can set up follows and webhook subscriptions for your users before you know their wallet addresses.

​
Why external IDs exist

Many apps identify users by an internal ID, not a wallet address. Your user might have an account in your system long before they connect a wallet. External IDs bridge this gap — you can start building a social graph for your users immediately, using identifiers you already have. When a user later connects a wallet, you add their address to the profile and everything flows naturally: their follows are already in place, their webhook subscriptions start delivering on-chain activity, and their profile is ready to appear on leaderboards.

​
How it works

Use the ext: prefix with any identifier in place of a wallet address or profile UUID. The ext: prefix tells Clicker to look up (or create) a profile using your app’s internal ID, scoped to your API key. 
ext:your-internal-user-id
For example, if your user’s ID is user_abc123, you’d reference them as ext:user_abc123 in API calls. External IDs are scoped to your API key. Two different partners can use the same external ID string without conflict — each resolves to a separate profile.

​
URL encoding

When using ext: identifiers in URL paths, the colon must be URL-encoded as %3A: 
PUT /v1/addresses/ext%3Auser_abc123/follow
In request bodies (JSON), use the ext: prefix as-is: 
{
  "walletAddresses": ["ext:user_abc123", "ext:user_xyz789"]
}

​
Setting up follows

Create follow relationships using your internal user IDs. Clicker creates stub profiles automatically on first use. 
# user_abc123 follows a trader by their wallet address
curl -X PUT https://api.clicker.xyz/v1/addresses/ext%3Auser_abc123/follow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targets": ["0x1234..."]}'
You can also use ext: identifiers in bulk follow operations and as follow targets.

​
Webhook subscriptions

Subscribe your users to webhook notifications using external IDs. When an ext: user is subscribed to a webhook and later gains wallet addresses, those addresses are automatically added as subscribers too. 
# Register a feed webhook with ext: subscribers
curl -X POST https://api.clicker.xyz/v1/webhooks/feed \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://yourapp.com/webhooks/clicker",
    "walletAddresses": ["ext:user_abc123", "ext:user_xyz789"]
  }'
You can mix ext: identifiers with regular wallet addresses in the same request.

​
Profile responses

When a profile has an external ID for your app, it appears in API responses as externalId: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "trader.yourapp.xyz",
  "addresses": ["0x1234..."],
  "externalId": "user_abc123",
  "metadata": { ... }
}
The externalId field is only present when the profile has an external ID for your API key. Other partners see their own external IDs, or no field at all. This field appears everywhere profiles are returned: profile lookups, follow responses, feed actors, leaderboard entries, and webhook payloads.

​
Adding addresses later

When your user connects a wallet, add their address to the existing profile. This is the “de-anonymization” step — the stub profile becomes a full profile with on-chain activity. After addresses are added:
  • The profile starts appearing in feeds and leaderboards
  • Webhook subscriptions automatically expand to cover the new addresses
  • The user’s existing follows remain intact
  • The externalId field continues to appear in responses alongside the addresses

​
Limitations

  • External IDs are permanent — once assigned to a profile, they cannot be reassigned to a different profile.
  • A profile can have one external ID per partner.
  • Profiles with only external IDs (no addresses) cannot author feed items, appear on leaderboards, or have PnL. They can follow other profiles and receive webhook notifications.
  • External IDs cannot be followed by other users — only profiles with addresses can be followed.