How to Build an AI Prediction Market Arbitrage Agent With an API and SDK

What is an AI prediction market arbitrage agent?

It is a workflow that combines deterministic market infrastructure with a model that can interpret and communicate the result. The model is not the price engine. It should not infer book depth from a chart, decide that two similar titles have identical settlement rules or estimate fees from memory.

A safe division of labor looks like this:

The architecture is intentionally uneven. Deterministic systems do the jobs where one wrong field can lose money. The model handles the jobs where language and prioritization add value.

Why should the agent use a normalized API?

A multi-venue agent otherwise has to understand every venue's identifiers, outcome labels, price formats, book shapes and authentication model. That knowledge changes frequently and consumes prompt space while still leaving room for subtle mistakes.

Predictefy exposes 15+ served venues through one normalized contract. The agent can call the same market and order-book method family while the response keeps venue identity, timestamps, provenance and capabilities. Cross-venue clusters connect equivalent contracts, and the arbitrage endpoint performs a bounded assessment against live asks.

This does not make all venues identical. An unsupported capability still returns NOT_SUPPORTED. Synthetic books remain labeled. Data coverage does not imply that hosted execution exists for the venue. The normalization removes unnecessary differences without hiding the ones that affect a decision.

What data should the agent receive?

Give the agent the smallest evidence package that can support the requested decision:

• Stable cluster and market identifiers.
• Venue and outcome for both legs.
• The requested contract count.
• Live acquisition cost and available depth for each leg.
• Fees included by the assessment.
• asOf timestamps and provenance.
• Resolution-equivalence status.
• The executable flag and every rejection reason.

Do not replace structured evidence with a paragraph saying that the trade "looks good." An agent should be able to quote the fields behind its summary and abstain when one is missing.

How do you create a read-only agent tool with the SDK?

Install the current beta and wrap only the assessed method:

npm install @predictefy/sdk@1.0.0-beta.9

import Predictefy from '@predictefy/sdk';

const client = new Predictefy({
  apiKey: process.env.PREDICTEFY_API_KEY,
});

type ScanInput = {
  contracts: number;
};

export async function scanArbitrage(input: ScanInput) {
  if (!Number.isInteger(input.contracts) || input.contracts < 1) {
    throw new Error('contracts must be a positive integer');
  }

  return client.router.fetchArbitrage({
    contracts: input.contracts,
    executableOnly: false,
    limit: 50,
  });
}

Expose the wrapper through the tool system used by your model provider. Keep the tool schema narrow: a positive integer contract count, optional approved venue filters and a server-enforced maximum. Do not accept arbitrary URLs, raw credentials or executable code from the model.

What instructions should the agent follow?

Give the agent an explicit decision contract. For example:

You analyze prediction market arbitrage evidence.

Rules:
1. Call the assessed arbitrage tool. Never infer a trade from titles alone.
2. Treat executable=false as rejected, even when the displayed edge is positive.
3. Report every rejection reason without rewriting it.
4. Reject stale evidence under the configured age limit.
5. Never call synthetic depth executable.
6. Never claim a fill, guaranteed return or risk-free profit.
7. Produce a proposal only. Do not build, sign or submit an order.
8. If required evidence is missing, abstain and say what is missing.

A prompt is not a security boundary, but it defines the behavior you can evaluate. The actual security boundary is the tool set and credentials. A read-only key and a tool list with no execution function are stronger than asking a fully privileged agent to behave.

How should the policy engine qualify a proposal?

Run deterministic checks after the tool response and before the model sees an approved candidate.

The agent can explain why a rule failed, but it cannot override the rule. If an analyst wants an exception, that becomes a separate human decision with its own record.

What should the agent's proposal contain?

Keep proposals structured and short enough to review under time pressure:

Status: REVIEW REQUIRED
Assessment time: 2026-09-17T08:14:22Z
Requested size: 100 paired contracts

Leg A: venue, market, outcome, bounded average cost
Leg B: venue, market, outcome, bounded average cost

Net assessed edge: value returned by the API
Resolution gate: passed
Book source: live and non-synthetic on both legs
Warnings: snapshot only; liquidity is not reserved

Action: approve, reject or rescan

The proposal should contain exact identifiers even if the interface also displays friendly titles. Titles help a person understand the event. Identifiers keep the execution layer from acting on the wrong contract.

Can the Predictefy MCP server power the agent?

Yes. The official MCP server gives compatible AI clients a curated tool surface over Predictefy. The current package is @predictefy/mcp@1.0.0-beta.9.

npx -y @predictefy/mcp@1.0.0-beta.9

The default MCP surface exposes 33 read, intelligence and platform tools. Its ten execution and collateral tools are off unless the operator sets MCP_ENABLE_TRADE=true or 1. No tool both builds and submits an order.

For a first arbitrage agent, leave trade tools disabled. Use tools such as cross-venue matching, discrepancies and assessed arbitrage to produce evidence. Adding execution later should be an explicit system change, not a prompt edit.

How should human approval and execution work?

Approval must bind to the exact proposal. Record the cluster, venue market IDs, sides, size, price limits and assessment timestamp. If any material field changes, invalidate the approval and rescan.

Execution then follows its own controlled flow:

1. Confirm the live execution service currently supports both venue lanes.
2. Reassess the exact size immediately before building.
3. Build unsigned venue-shaped artifacts with stable idempotency keys.
4. Validate the artifacts against the approved bounds.
5. Sign inside the user's process with venue-specific credentials.
6. Submit and monitor both legs, with an explicit policy for rejection or partial fill.

Predictefy's reads API never holds the signer. The separate execution service revalidates artifacts and spend caps, but the operator remains responsible for current venue access, funding and leg risk.

What can go wrong with an AI arbitrage agent?

Calling a gap arbitrage. The model sees two probabilities and ignores asks, depth or rules. Fix this by giving it the assessed surface and refusing unqualified inputs.

Using stale evidence. A persuasive explanation outlives the book snapshot. Put freshness in deterministic policy and display the assessment time prominently.

Dropping rejection reasons. The model summarizes a row but omits insufficient_depth. Require a lossless reasons field in the proposal schema.

Confusing similarity with equivalence. A high matching score becomes a false guarantee. Treat similarity as a retrieval signal and resolution equivalence as its own gate.

Giving the model credentials. A prompt injection or malformed source then reaches trading authority. Keep API and venue secrets in the tool host, expose bounded functions and begin with read scope.

Ignoring the second leg. The first order fills and the other does not. Define price bounds, submission order and partial-fill behavior before enabling execution.

How do you test the agent before live use?

1. Feed it an attractive row with executable=false and confirm it rejects it.
2. Remove the timestamp and confirm it abstains.
3. Mark one book synthetic and confirm it refuses the executable label.
4. Add a resolution mismatch and confirm no positive edge can override it.
5. Simulate a rate limit or unavailable assessment and confirm it does not reuse old evidence.
6. Attempt prompt injection inside a market title and confirm the title remains untrusted data.
7. Run the entire workflow with trade tools absent before considering any execution permission.

The success metric is not how often the agent finds a trade. It is whether every recommendation can be traced to current structured evidence and whether the system reliably refuses when that evidence is incomplete.

Frequently Asked Questions