Create Position

Place a prediction position in an active SpotOn game.

Endpoint

POST https://api.metafide.io/v1/surge/games/spot

Headers

Header	Value
Accept	*/*
Content-Type	application/json
x-api-key	Your Metafide API key

Request Body

{
  "gid": "489808",
  "c": "USDC",
  "a": "BTC_USDT",
  "sp": "67273",
  "f": "67.5",
  "pw": "0x3d6520782B3fD66507A042a31Af5155da9e2bb63",
  "n": "testnet",
  "it": 86400
}

Request Fields

Field	Type	Required	Description
gid	string	Yes	The unique identifier of the game to place a position in. Get this from the Spot Games endpoint
c	string	Yes	The currency to stake (e.g. USDC)
a	string	Yes	The asset you are predicting (e.g. BTC_USDT)
sp	string	Yes	Your predicted closing price for the asset
f	string	Yes	The amount you are staking
pw	string	Yes	Your wallet address
n	string	Yes	The network to place the position on (e.g. mainnet, testnet)
it	number	Yes	The game interval in seconds (e.g. 60, 3600, 86400)

Example Request

// Node 18+ has native fetch — no import needed

const url = 'https://api.metafide.io/v1/surge/games/spot';

const options = {
  method: 'POST',
  headers: {
    'Accept': '*/*',
    'Content-Type': 'application/json',
    'x-api-key': 'metafide_11111111111111111111111111111',
  },
  body: JSON.stringify({
    gid: '489808',
    c: 'USDC',
    a: 'BTC_USDT',
    sp: '67273',
    f: '67.5',
    pw: '0x3d65207Af82B3fD66507A042a315155da9e2bb63',
    n: 'testnet',
    it: 86400,
  }),
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

tip

Use the Spot Games endpoint to get the current gid before placing a position. Make sure can_place_position is true before submitting.

warning

Each user can place up to 10 positions per game per interval. Exceeding this limit or submitting a duplicate position will return a 409 Conflict error.

Response

{
  "gid": "489808",
  "c": "USDC",
  "a": "BTC_USDT",
  "id": 1,
  "f": "67.5",
  "sp": "67273",
  "cm": false,
  "cmt": null,
  "w": "0",
  "r": null,
  "pw": "0x3d65207Af382B3fD66507A042a315155da9e2bb6",
  "win": null,
  "t": "1771507627221",
  "tx": null,
  "txid": "b7c8dbf1-dff3-4fdd-a829-cb563e293c24",
  "p": null,
  "created_at": "2026-02-19T13:27:07.223Z",
  "st": "success",
  "it": 86400,
  "n": "testnet",
  "username": "John Doe",
  "avatar": {
    "imageUrl": "/avatars/default.svg",
    "backgroundColor": "#4285f4"
  }
}

Response Fields

Field	Type	Description
gid	string	Unique identifier of the game the position was placed in
c	string	Currency used for the position
a	string	Asset the position was placed on
id	number	User ID of the position owner
f	string	The stake amount placed
sp	string	The predicted price submitted by the user
cm	boolean	Whether the position has been claimed
cmt	string | null	Claim transaction hash, null if not yet claimed
w	string	Projected winnings at the time of placement. Returns "0" until the game progresses
r	number | null	Projected return percentage, null until the game progresses
pw	string	The wallet address of the position owner
win	number | null	Final winnings, null if the game is still ongoing
t	string	Unix timestamp in milliseconds of when the position was placed
tx	string | null	Transaction hash of the position, null if not yet confirmed
txid	string	Internal unique identifier for the transaction
p	any | null	Additional position metadata, null if not applicable
created_at	string	ISO 8601 timestamp of when the position was created
st	string	Status of the position (e.g. success)
it	number	Game interval in seconds
n	string	Network the position was placed on
username	string	Display name of the position owner

avatar

Field	Type	Description
imageUrl	string	URL of the user's avatar image
backgroundColor	string	Hex color code of the avatar background