Documentación de la API

Empezar en 5 minutos

La API es JSON sobre HTTPS. Los importes y precios viajan como texto (por ejemplo "78000.5") para no perder precisión; las fechas son segundos Unix. Con ella puedes leer precios, abrir y cerrar posiciones y consultar tu cuenta desde tu propio programa, con las mismas reglas, costes y límites que el gráfico.

1. Crea una cuenta de práctica y guarda la clave (solo se muestra una vez):

   curl -X POST https://tapearena.com/v1/accounts

2. Mira el precio (no necesita clave):

   curl https://tapearena.com/v1/prices

3. Compra 0,05 BTC a mercado:

   curl -X POST https://tapearena.com/v1/orders -H "X-API-Key: TU_CLAVE" -H "content-type: application/json" \
     -d '{"symbol":"BTC","side":"buy","qty":"0.05"}'

4. Mira tu cuenta:

   curl https://tapearena.com/v1/account -H "X-API-Key: TU_CLAVE"

Cuenta simulada de 5.000 USDC, apalancamiento máximo 3×, comisión 0,035 % y deslizamiento dinámico. Todo es dinero simulado y con fines formativos.

Autenticación y claves

• Cada cuenta tiene una clave de API. Se envía en la cabecera X-API-Key de cada llamada que la requiere.
• La clave se crea con POST /v1/accounts y solo se muestra en esa respuesta: guárdala. El servidor guarda únicamente su huella, así que no se puede recuperar; si la pierdes, crea otra cuenta.
• Trátala como una contraseña: no la subas a repositorios públicos ni la pongas en código que se ejecute en un navegador.
• Sin clave o con una clave incorrecta, la respuesta es 401 invalid API key.

curl https://tapearena.com/v1/account -H "X-API-Key: tu_clave_aqui"

Dos formas de tener clave

• Tu cuenta de la competición: entra en el menú de usuario → Mi cuenta → sección API y pulsa «Generar clave». Se muestra una sola vez. Puedes generar otra cuando quieras (la anterior deja de funcionar al instante) o revocarla. Las órdenes entran en la misma cuenta que usas en el gráfico y compiten en la clasificación.
• Una cuenta de práctica: las que crea POST /v1/accounts. Son independientes de la competición.

Un mismo programa nunca necesita tu contraseña ni tu sesión web: solo la clave.

Conceptos que conviene conocer

• Símbolos: BTC, ETH y SOL (futuros perpetuos, precios reales de mercado).
• Lado y cantidad: side es buy o sell; qty son unidades del activo (0,05 = 0,05 BTC), no dólares.
• Una posición neta por símbolo. Con la API cada orden suma o resta a la misma posición. Comprar cuando estás en corto la reduce o la da la vuelta. Esto es distinto del gráfico, donde cada orden puede ser una operación independiente con su propio SL/TP.
• Gráfico y API en la misma cuenta: las órdenes por API forman una posición neta aparte de las operaciones del gráfico, pero ambas cuentan para el límite de apalancamiento (un único tope para todo). Para evitar sorpresas, usa una vía u otra en cada activo.
• Costes: comisión 0,035 % del importe en cada ejecución, más un deslizamiento en las órdenes de mercado: 2 puntos básicos más 1 por cada 100.000 USDC de importe.
• Apalancamiento: el importe total de tus posiciones no puede pasar de 3× tu capital (422 leverage limit exceeded). Si tu capital baja del 0,5 % del importe que tienes en posiciones, el sistema liquida todo al instante.
• Capital (equity) = saldo + ganancia o pérdida no realizada de las posiciones abiertas. El saldo (balance) ya descuenta comisiones.
• Límites de riesgo: si al cierre del día (00:00 UTC) pierdes más de lo permitido, tus posiciones se cierran y la cuenta queda bloqueada (423) hasta rehabilitarla. Mira la sección de límites de riesgo.

Referencia: cuenta y órdenes

POST /v1/accounts público, sin clave

Crea una cuenta de práctica y devuelve su clave de API. La clave solo se muestra aquí.

Ejemplo

curl -X POST https://tapearena.com/v1/accounts

import requests
r = requests.post("https://tapearena.com/v1/accounts").json()
api_key = r["api_key"]   # guárdala

Respuesta

{
  "account": "acc_8bc1ab396b5f",
  "api_key": "cAEFMlBbxnsECOQbifLiaY6BHfXoYFrOYzmYmWqfKp0",
  "balance": "5000",
  "note": "store the key now; it cannot be shown again"
}

Errores

• 422 · enrolment closed (opens until the season starts) — La temporada ya empezó: solo se puede inscribir una cuenta antes del inicio.
• 422 · name already taken — Ese nombre ya está en uso.
• 422 · country must be a 2-letter ISO code — El país debe ser un código de dos letras.
• 429 · too many accounts created from your address: at most N per M minutes — Demasiadas cuentas creadas desde tu dirección (solo si el servicio aplica este límite).

GET /v1/prices público, sin clave

Último precio de cada activo. Se actualiza cada segundo.

Ejemplo

curl https://tapearena.com/v1/prices

Respuesta

{
  "BTC": "78000",
  "ETH": "2300",
  "SOL": "150"
}

GET /v1/account requiere clave

Tu cuenta: saldo, capital, si está liquidada y tus posiciones abiertas (una por símbolo, con cantidad con signo: positiva = largo, negativa = corto).

Ejemplo

curl https://tapearena.com/v1/account -H "X-API-Key: TU_CLAVE"

import requests
H = {"X-API-Key": "TU_CLAVE"}
print(requests.get("https://tapearena.com/v1/account", headers=H).json()["equity"])

Respuesta

{
  "account": "acc_8bc1ab396b5f",
  "balance": "4998.63",
  "equity": "4997.84",
  "liquidated": false,
  "positions": {
    "BTC": {
      "qty": "0.05",
      "entry": "78015.90",
      "sl": null,
      "tp": null
    }
  }
}

Errores

• 401 · invalid API key — La clave falta o es incorrecta.
• 429 · rate limit exceeded — Demasiadas peticiones seguidas: espera un momento.

POST /v1/orders requiere clave

Envía una orden de mercado (se ejecuta al momento) o límite (se ejecuta cuando el precio llega al tuyo). Puedes añadir Stop Loss y Take Profit, que se asocian a la posición. Ver el ciclo de vida.

Ejemplo

curl -X POST https://tapearena.com/v1/orders -H "X-API-Key: TU_CLAVE" -H "content-type: application/json" \
  -d '{"symbol":"BTC","side":"buy","qty":"0.05","sl":"74000","tp":"84000"}'

import requests
H = {"X-API-Key": "TU_CLAVE"}
r = requests.post("https://tapearena.com/v1/orders", headers=H, json={"symbol": "BTC", "side": "buy", "qty": "0.05"})
print(r.status_code, r.json())

Respuesta

// orden de mercado (o límite ya ejecutable): 201
{
  "status": "filled",
  "symbol": "BTC",
  "side": "buy",
  "qty": "0.05",
  "price": "78015.90",
  "fee": "1.365",
  "realized_pnl": "0"
}

// orden límite que espera: 201
{
  "status": "pending",
  "order_id": 1,
  "symbol": "BTC",
  "side": "buy",
  "qty": "0.02",
  "price": "70000"
}

Errores

• 422 · leverage limit exceeded — La orden haría que el importe total pasara del apalancamiento máximo.
• 422 · no price for symbol — Símbolo desconocido (usa BTC, ETH o SOL).
• 422 · a limit order needs a price — Una orden límite necesita el campo price.
• 422 · at most 20 pending orders — Ya tienes 20 órdenes límite pendientes.
• 422 · account liquidated — Tu cuenta fue liquidada y no puede operar.
• 422 · season not active — La temporada de tu cuenta no está en curso.
• 422 · stop loss must be below the current price for a long position — El Stop Loss o el Take Profit están en el lado equivocado del precio (hay mensajes equivalentes para cada caso).
• 423 · account blocked: a risk limit was exceeded; rehabilitate it — Tu cuenta está bloqueada por superar un límite de riesgo.
• 429 · rate limit exceeded — Demasiadas peticiones seguidas.
• 429 · order limit: at most 20 per hour and 200 per day per account (HFT is prohibited) — Has llegado al máximo de órdenes por hora (20) o por día (200); el trading de alta frecuencia está prohibido.

POST /v1/stops requiere clave

Cambia o quita el Stop Loss y el Take Profit de tu posición en un símbolo. Envía null para quitar uno.

Ejemplo

curl -X POST https://tapearena.com/v1/stops -H "X-API-Key: TU_CLAVE" -H "content-type: application/json" \
  -d '{"symbol":"BTC","sl":"75000","tp":null}'

Respuesta

{
  "symbol": "BTC",
  "sl": "75000",
  "tp": null
}

Errores

• 422 · no open position in that symbol — No tienes posición abierta en ese símbolo.
• 422 · stop loss must be above the current price for a short position — Stop Loss o Take Profit en el lado equivocado del precio (según largo o corto).
• 423 · account blocked: a risk limit was exceeded; rehabilitate it — Cuenta bloqueada por riesgo.

GET /v1/orders/open requiere clave

Tus órdenes límite pendientes (máximo 20 a la vez).

Ejemplo

curl https://tapearena.com/v1/orders/open -H "X-API-Key: TU_CLAVE"

Respuesta

[
  {
    "id": 1,
    "symbol": "BTC",
    "side": "buy",
    "qty": "0.02",
    "price": "70000",
    "sl": "68000",
    "tp": "76000",
    "created": 1794425798.33,
    "origin": "manual",
    "ref": ""
  }
]

DELETE /v1/orders/{order_id} requiere clave

Cancela una orden límite pendiente.

Ejemplo

curl -X DELETE https://tapearena.com/v1/orders/1 -H "X-API-Key: TU_CLAVE"

Respuesta

{
  "cancelled": 1
}

Errores

• 404 · unknown order — La orden no existe, ya se ejecutó o no es tuya.

GET /v1/fills requiere clave

Todas las ejecuciones de tu cuenta, de la más antigua a la más reciente. origin dice de dónde vino: api (esta API), manual (el gráfico), conditional (orden condicional), strategy (estrategia del Laboratorio) o system (liquidación). realized_pnl es la ganancia cerrada en esa ejecución, sin descontar la comisión.

Ejemplo

curl https://tapearena.com/v1/fills -H "X-API-Key: TU_CLAVE"

Respuesta

[
  {
    "symbol": "BTC",
    "side": "buy",
    "qty": "0.05",
    "price": "78015.90",
    "fee": "1.365",
    "realized_pnl": "0",
    "liquidation": false,
    "origin": "api",
    "ref": ""
  }
]

Cómo se ejecuta una orden

• Mercado: se ejecuta enseguida al último precio más el deslizamiento. Recibes status: "filled" con el precio real, la comisión y, si cerraste algo, el realized_pnl.
• Límite: si el mercado ya está en tu precio o mejor, se ejecuta al momento al precio actual y sin deslizamiento. Si no, queda "pending" y se ejecuta, entera, cuando el precio la toca. No se simula profundidad ni cola de prioridad.
• Stop Loss y Take Profit: se asocian a la posición. Si el precio llega al Stop Loss, la posición se cierra a mercado con deslizamiento; al Take Profit, se cierra al precio fijado. Con una orden límite pendiente se aplican cuando se ejecuta.
• Apalancamiento: se comprueba al enviar y otra vez al ejecutarse una límite; si en ese momento no cabe, la orden se descarta.

Referencia: datos públicos

Estos endpoints no necesitan clave. Se almacenan en caché unos segundos, así que no tiene sentido consultarlos con más frecuencia.

GET /v1/seasons público, sin clave

Las temporadas, con sus reglas (mínimos, caída máxima permitida) y su estado: upcoming, live o ended.

Ejemplo

curl https://tapearena.com/v1/seasons

Respuesta

[
  {
    "id": 1,
    "name": "Noviembre 2026",
    "kind": "monthly",
    "start": 1793491200.0,
    "end": 1796083200.0,
    "min_trades": 3,
    "max_drawdown": "0.5",
    "min_active_days": 2,
    "min_trade_frac": "0.01",
    "status": "live"
  }
]

GET /v1/leaderboard público, sin clave

La clasificación de una temporada: posición, nombre, rentabilidad, caída máxima, operaciones, días activos y puntuación. Con include_unranked=true añade las cuentas que aún no clasifican, con el motivo.

Ejemplo

curl 'https://tapearena.com/v1/leaderboard?limit=5'

GET /v1/participants/{account} público, sin clave

El historial público de una cuenta: estadísticas, curva de capital (equity, lo que mide la clasificación) y de balance (el dinero con las operaciones cerradas), posiciones y operaciones. Las operaciones de cuentas de usuario se publican con 1 hora de retraso para que nadie copie una estrategia en vivo.

Ejemplo

curl 'https://tapearena.com/v1/participants/acc_8bc1ab396b5f?rows=50'

GET /v1/curves público, sin clave

Las curvas de capital de todos los participantes de una temporada (rentabilidad frente al inicio), para dibujar la comparativa.

Ejemplo

curl 'https://tapearena.com/v1/curves?max_points=60'

GET /v1/benchmarks público, sin clave

Lo que habría ganado simplemente comprar y mantener cada activo desde el inicio de la temporada: la línea de referencia para medir tu estrategia.

Ejemplo

curl https://tapearena.com/v1/benchmarks

Errores y códigos de estado

Los errores devuelven un JSON {"detail": "…"}. Los errores de validación del cuerpo (por ejemplo, side distinto de buy o sell) devuelven en detail una lista con el campo y el motivo.

Límites de uso

Buenas prácticas: no consultes más de una vez por segundo; reutiliza una sola conexión; ante un 429 espera antes de reintentar; no repitas una orden rechazada con los mismos datos; guarda tu clave fuera del código. El uso abusivo (automatizar la creación de cuentas, saturar el servicio, explotar errores o precios obsoletos) puede conllevar la cancelación del usuario.

Ejemplos completos

Python con requests: comprar, poner stops y salir

import requests, time

BASE = "https://tapearena.com"
H = {"X-API-Key": "TU_CLAVE"}

def call(method, path, **kw):
    """Llama a la API y reintenta si hay 429 (retroceso exponencial)."""
    for wait in (0.2, 0.5, 1, 2, 4):
        r = requests.request(method, BASE + path, headers=H, timeout=10, **kw)
        if r.status_code != 429:
            return r
        time.sleep(wait)
    return r

price = float(requests.get(BASE + "/v1/prices").json()["BTC"])
r = call("POST", "/v1/orders", json={"symbol": "BTC", "side": "buy", "qty": "0.05",
                                       "sl": str(round(price * 0.97)), "tp": str(round(price * 1.06))})
print(r.status_code, r.json())          # 201 {"status": "filled", ...}
print(call("GET", "/v1/account").json()["positions"])

# salir: vender lo mismo que tienes
pos = call("GET", "/v1/account").json()["positions"]["BTC"]["qty"]
print(call("POST", "/v1/orders", json={"symbol": "BTC", "side": "sell", "qty": pos}).json())

Una orden límite y su cancelación

o = call("POST", "/v1/orders", json={"symbol": "ETH", "side": "buy", "qty": "1", "type": "limit", "price": "2000"}).json()
if o["status"] == "pending":
    print("esperando, id", o["order_id"])
    call("DELETE", f"/v1/orders/{o['order_id']}")

Con el cliente de un solo fichero

from client import Client
c, info = Client.register("https://tapearena.com")      # guarda info["api_key"]
c.buy("BTC", "0.05")
c.target("BTC", 0.5, leverage=1)       # llevar la posición al 50 % del capital
c.close("BTC")

Vigilar el precio y calcular una media

import requests, time
precios = []
for _ in range(30):                       # un precio por segundo
    precios.append(float(requests.get("https://tapearena.com/v1/prices").json()["BTC"]))
    time.sleep(1)
media = sum(precios) / len(precios)
print("BTC por encima de su media de 30 s:", precios[-1] > media)

JavaScript (fetch)

const H = {"X-API-Key": "TU_CLAVE", "content-type": "application/json"};
const r = await fetch("https://tapearena.com/v1/orders", {method: "POST", headers: H,
  body: JSON.stringify({symbol: "BTC", side: "buy", qty: "0.05"})});
console.log(r.status, await r.json());

Estos ejemplos usan una cuenta de práctica. Ejecuta tus programas en tu servidor o tu ordenador, no en una página web pública, para no exponer la clave.

Cliente Python de un solo fichero

Un único archivo, sin dependencias: cópialo junto a tu programa. Descárgalo con curl -O https://tapearena.com/sdk/client.py.

from client import Client, run
c, info = Client.register("https://tapearena.com")     # guarda info["api_key"]
c.prices(); c.buy("BTC", "0.1"); c.target("BTC", 0.5, leverage=2); c.close("BTC")
run(c, "BTC", lambda hist: 1.0 if hist[-1] > hist[0] else -1.0, every=60)

• Client.register(url) crea una cuenta de práctica; Client(url, api_key=…) reutiliza una existente.
• prices(), account(), position(sym), fills(), leaderboard(), seasons().
• buy(), sell(), order(), target(sym, fracción, leverage=…) (lleva la posición a una fracción del capital) y close(sym).
• run(client, símbolo, estrategia, every=segundos) ejecuta en bucle una función que recibe el historial de precios y devuelve un objetivo entre −1 y 1.

Activos disponibles

Se opera con futuros perpetuos de criptomonedas, cotizados en USDC y con dinero simulado. Hoy hay 3 activos; cualquier otro símbolo se rechaza.

Pulsa un símbolo para ver su gráfico. Puedes estar largo (comprar) o corto (vender) en cada uno, con posición neta por símbolo y hasta 10x de apalancamiento sobre tu capital total. Se pueden combinar varios activos en la misma cuenta.

Datos históricos

TapeArena no permite descargar históricos de precios: la API solo da los precios actuales (y tu programa puede ir guardando los que recibe). Si quieres probar una estrategia con historia, descárgala de una fuente pública y trabaja con ella en tu equipo:

• Binance Public Data (data.binance.vision): gratuita. Velas (OHLCV) de futuros perpetuos USDT-M, como BTCUSDT, ETHUSDT y SOLUSDT, en ficheros diarios y mensuales desde 2020.
• Tardis.dev: datos operación a operación, libro de órdenes y funding de muchos mercados de derivados. Es de pago, con el primer día de cada mes gratis para probar.

Los precios de otros mercados difieren ligeramente de los de TapeArena, así que úsalos para investigar y no esperes resultados idénticos. Revisa las condiciones de uso de cada fuente.

Lo que aún no está en la API

La API cubre la operativa básica con una posición neta por símbolo. Estas funciones existen en el entorno gráfico y todavía no tienen endpoint:

• Operaciones independientes (cerrar o reducir una operación concreta, SL/TP por operación).
• Órdenes condicionales, OCO y caducidad.
• Estrategias del Laboratorio (guardar, habilitar, cartera).
• Rehabilitar una cuenta bloqueada (se hace desde «Mi cuenta»).

Esta lista se actualizará aquí cuando se amplíe la API.

Preguntas frecuentes

¿Cómo consigo mi clave de API?

Para tu cuenta de la competición, desde Mi cuenta → API → «Generar clave». Para una cuenta de práctica, con POST /v1/accounts. En ambos casos se muestra una sola vez: guárdala.

¿Por qué recibo un error 429?

Superaste el límite de 10 peticiones por segundo por clave (ráfaga de 20) o el de órdenes por hora y por día. Espera y reintenta con retroceso exponencial.

¿Qué diferencia hay entre una orden de mercado y una límite?

La de mercado se ejecuta al instante al último precio más el deslizamiento; la límite se ejecuta cuando el precio llega al tuyo, entera y sin deslizamiento.

¿Puedo tener varias posiciones en el mismo activo con la API?

No: con la API hay una posición neta por símbolo. Comprar y vender suma y resta a esa misma posición.