Coin Flipper API

About the Coin Flipper API

A coin flip API for apps, games and lessons that need a heads or tails result they can log. Each toss uses fair probability (50/50), and the response lists every result in order with the heads and tails counts and the first and last flip, so a coin toss can be shown, stored or replayed exactly as it happened.

The Free plan flips one coin per request. That covers a tie-breaker button, choosing who goes first in a game, a random yes or no in a chat bot, or a coin flipper widget on a web page.

Paid plans let you set how many coins to flip, up to 10,000 in one call, and add the statistics that make a large batch worth having: heads and tails percentages, the longest streak and which side it was, and a fairness indicator that shows whether the split stayed close to even. That suits probability lessons, simulations, testing code that consumes random outcomes, and showing how streaks appear in genuinely random sequences.

How it works

Each flip draws one pseudo-random number and calls it Heads when the value is below 0.5 and Tails otherwise, so both sides have the same chance and no flip depends on the one before it. flips holds the results in the order they were generated, total_flips is how many were made, and heads_count and tails_count always add up to it. first_flip and last_flip are the first and last entries of that array.

The flips parameter defaults to 1 and accepts up to 10,000. Larger values are capped at 10,000, and values below 1 are treated as 1. The array grows with the count, so a 10,000-flip response carries 10,000 strings.

heads_percentage and tails_percentage are the counts divided by total_flips, times 100, rounded to two decimals: 30 means 30%, not 0.30. longest_streak scans the sequence for the longest run of identical results; length is the run size and type is the side. When two runs tie, the earlier one is reported, and a single flip has a streak of 1.

is_fair is true when the heads percentage is strictly within 10 percentage points of 50. It is a fixed tolerance band, not a statistical test, so small batches often read false: three heads in ten flips is 30% and returns false although nothing is wrong with the generator. Judge fairness on large batches.

On the Free plan the flips parameter is removed, so every call makes exactly one flip, and the percentage fields and is_fair are null.

What people use it for

Decision Making

Make random decisions and choices using fair coin flip probability

Gaming

Implement coin flip mechanics for games, sports, and random selection features

Probability Teaching

Demonstrate probability concepts and random distributions in education

Simulations

Run probability experiments and test statistical concepts with multiple flips

Without writing code

The Coin Flip widget from WidgetSpark flips one on your desktop.

Ways to call it

One endpoint, many ways in — REST with JSON, XML, YAML and CSV, plus GraphQL and an MCP interface for AI agents.

JSON

Default REST response

XML

Markup format

YAML

Human-readable

CSV

Tabular export

Beta

GraphQL

Query language

New

MCP

For AI agents

Request parameters — GET /v1/coinflipper

Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them. Anything not listed here is dropped rather than passed through.

Optional

1
2

curl "https://api.apiverve.com/v1/coinflipper?flips=10" \
  -H "x-api-key: YOUR_API_KEY"

Authentication

Send your key in the x-api-key header. That is the only auth step — no token exchange, and no per-endpoint scope to configure.

Response — GET /v1/coinflipper

Every APIVerve endpoint returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
  "status": "ok",
  "error": null,
  "data": {
    "total_flips": 10,
    "flips": [
      "Tails",
      "Heads",
      "Heads",
      "Tails",
      "Tails",
      "Heads",
      "Tails",
      "Tails",
      "Tails",
      "Tails"
    ],
    "heads_count": 3,
    "tails_count": 7,
    "heads_percentage": 30,
    "tails_percentage": 70,
    "longest_streak": {
      "length": 4,
      "type": "Tails"
    },
    "first_flip": "Tails",
    "last_flip": "Tails",
    "is_fair": false
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Response headers

Every response carries your balance, so your own code always knows where it stands without polling anything. All four are exposed to browsers through CORS.

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change.

What a call costs — 1 credits per call

Credits are shared across every APIVerve API — one balance, one key, one bill. Failed requests never count against it, so a rejected input costs nothing.

Calls are what the credits buy at this API's rate — spend them here, on any of the other APIs, or across both. Nothing is reserved per endpoint.

Zero-code embed — one snippet, no backend

Drop an interactive Coin Flipper form onto any page. The widget calls the API for you, so no key ever appears in your markup and there is nothing to deploy.

Changelog — Coin Flipper API

Every change to this endpoint, newest first. Breaking changes ship as a new version and the previous one keeps serving — response fields are added, never removed or retyped in place, so an integration written against v1 keeps working.

Currently v1