External Multiplier API

The External Multiplier API lets campaign creators plug in their own eligibility and weighting logic — such as token-gating, allowlists, or reputation scores — without modifying Rally’s intelligent contracts.

When configured, Rally’s intelligent contract calls your API before evaluating each submission. Your API returns a multiplier that scales the user’s final reward share up or down.

How It Works

1. Configure

Set your API URL in Step 4 (Evaluation) during campaign creation

2. User Submits

A content creator submits a tweet to your campaign

3. Rally Calls Your API

The contract POSTs the user’s X ID to your endpoint

4. Score Adjusted

The returned multiplier scales the user’s reward share

API Specification

Request

Your endpoint receives a POST request with the following format:

Method: POST
Content-Type: application/json
Body:


{
  "xId": "1234567890"
}

Field	Type	Description
`xId`	string	The user’s X (Twitter) numeric ID

Response

Your endpoint must return a JSON response with a multiplier field:

Content-Type: application/json
Body:


{
  "multiplier": "1.25"
}

Field	Type	Description
`multiplier`	string or number	The score multiplier to apply. Supports up to 18 decimal places.

Multiplier Values

Value	Effect
`"1.0"`	No change (default behavior)
`"0"` or `"0.0"`	User gets zero score — LLM analysis is skipped entirely
`"2.5"`	User’s reward share is multiplied by 2.5x
`"0.5"`	User’s reward share is halved
Negative values	Treated as 0 (zero score)

Response Handling

Rally handles your API responses as follows:

HTTP Status	Behavior	Use Case
200	Parse `{"multiplier": "X"}` and apply	User is eligible
4xx (400–499, except below)	Multiplier = 0, submission zero-scored	User is not eligible
401, 403, 429	Transient error — submission retried	API auth issue or rate limit
5xx	Transient error — submission retried	Server error
Parse error / missing key	Defaults to `1.0` (fail-open)	Graceful degradation

⚠️

Important: If your API returns a 4xx status (other than 401/403/429), the user receives a zero score and the LLM analysis is skipped entirely. Use this to deny ineligible users.

Fail-open behavior: If Rally cannot parse your response (malformed JSON, missing multiplier key), the multiplier defaults to 1.0 — the user receives their full score. This prevents API bugs from accidentally blocking all participants.

Scoring Formula

The external multiplier is applied after the alpha distribution curve:


final_score = raw_score^alpha × multiplier

raw_score — the AI-evaluated quality score from LLM analysis
alpha — the campaign’s distribution curve exponent
multiplier — the value returned by your external API

The user’s share of the period’s reward pool is proportional to their final_score relative to all other participants.

Example Implementations

Token-Gating (Node.js / Express)

Only reward users who hold your token:


app.post('/rally-multiplier', async (req, res) => {
  const { xId } = req.body;
 
  // Look up the user's wallet by their X ID
  const wallet = await db.getWalletByXId(xId);
  if (!wallet) {
    return res.status(404).json({ multiplier: "0" });
  }
 
  // Check token balance
  const balance = await tokenContract.balanceOf(wallet);
  if (balance.isZero()) {
    return res.status(200).json({ multiplier: "0" });
  }
 
  // Boost based on holdings
  if (balance.gte(ethers.parseUnits("10000", 18))) {
    return res.json({ multiplier: "2.0" });
  }
 
  return res.json({ multiplier: "1.0" });
});

Allowlist (Python / Flask)

Restrict participation to a known set of users:


ALLOWED_USERS = {"123456", "789012", "345678"}
 
@app.route("/rally-multiplier", methods=["POST"])
def rally_multiplier():
    x_id = request.json.get("xId")
 
    if x_id not in ALLOWED_USERS:
        return jsonify({"multiplier": "0"}), 404
 
    return jsonify({"multiplier": "1.0"})

Reputation Score (Node.js)

Weight rewards by an internal reputation system:


app.post('/rally-multiplier', async (req, res) => {
  const { xId } = req.body;
 
  const reputation = await getReputationScore(xId); // 0.0 to 5.0
  const multiplier = (reputation / 5.0).toFixed(2);
 
  return res.json({ multiplier });
});

Testing Your API

Before deploying your campaign, you can test your external multiplier API directly from the Rally interface:

Enter your API URL during campaign creation
Use the Test button to send a test request with a sample X ID
Verify the response status, raw body, and parsed multiplier

You can also test manually with cURL:


curl -X POST https://your-api.com/rally-multiplier \
  -H "Content-Type: application/json" \
  -d '{"xId": "1234567890"}'

Expected response:


{
  "multiplier": "1.25"
}

Best Practices

Keep response times low — Your API is called during submission evaluation. Aim for under 2 seconds.

Return string multipliers — While numbers work, strings like "1.25" avoid floating-point precision issues.

Handle unknown users gracefully — Return {"multiplier": "0"} with a 404 status to deny unknown users, or {"multiplier": "1.0"} with 200 to allow everyone by default.

Ensure high availability — If your API is down (5xx), submissions are retried rather than rejected. Persistent downtime will block users from participating.

Use HTTPS — Your endpoint URL must use http:// or https://. HTTPS is strongly recommended for production.