API v1 · read-only

Documentación de la API CASK

Consulta saldos, direcciones, tu directorio y cotizaciones de swap en tiempo real desde cualquier aplicación. HTTP/REST estándar, en el lenguaje que prefieras.

CASK API Documentation

Query balances, addresses, your directory, and real-time swap quotes from any application. Standard HTTP/REST, in the language you prefer.

URL base Base URL https://cask.network/api/v1

Introducción

La API de CASK te permite leer información de tu cuenta de forma programática: saldos, direcciones, tu directorio de contactos, y cotizaciones de swap en tiempo real (incluyendo cross-chain).

Esta versión (v1) es solo de lectura. No mueve fondos ni ejecuta operaciones. Es ideal para:

Bots de trading que necesitan cotizaciones de swap
Paneles y dashboards que muestran saldos
Integraciones con otras aplicaciones
Automatización de consultas

La API es HTTP/REST estándar. Funciona desde cualquier lenguaje que pueda hacer una petición HTTP: Python, JavaScript, PHP, Go, Ruby, Java, C#, Rust, y más.

Introduction

The CASK API lets you read your account information programmatically: balances, addresses, your contact directory, and real-time swap quotes (including cross-chain).

This version (v1) is read-only. It does not move funds or execute operations. It's ideal for:

Trading bots that need swap quotes
Panels and dashboards that display balances
Integrations with other applications
Automating queries

The API is standard HTTP/REST. It works from any language that can make an HTTP request: Python, JavaScript, PHP, Go, Ruby, Java, C#, Rust, and more.

Autenticación

CASK usa autenticación por token bearer: cada petición lleva dos credenciales en los headers.

Obtener tus credenciales

Abre tu wallet en cask.network
Entra al menú de tu cuenta → API / Desarrolladores
Toca Crear nueva API key
Elige un nombre, los permisos y opcionalmente una whitelist de IPs
Guarda la key y el secret (el secret solo se muestra una vez)

Recibirás dos valores: la API Key (pública, empieza con cask_pk_) y el API Secret (privado, empieza con cask_sk_).

Usar tus credenciales

Envía ambos valores en los headers de cada petición:

Authentication

CASK uses bearer token authentication: each request carries two credentials in the headers.

Get your credentials

Open your wallet at cask.network
Go to your account menu → API / Developers
Tap Create new API key
Choose a name, the permissions, and optionally an IP whitelist
Save the key and secret (the secret is shown only once)

You'll receive two values: the API Key (public, starts with cask_pk_) and the API Secret (private, starts with cask_sk_).

Use your credentials

Send both values in the headers of every request:

HTTP headers

X-Api-Key: cask_pk_tu_key
X-Api-Secret: cask_sk_tu_secret

Seguridad

La seguridad de tu cuenta depende de cómo manejes tus credenciales. Buenas prácticas:

Nunca compartas tu secret. Es como una contraseña. Quien lo tenga puede leer tus datos según los permisos de la key.
No lo pongas en código público (GitHub, front-end). Usa variables de entorno.
Usa siempre HTTPS. La API solo responde por HTTPS, que cifra tus credenciales en tránsito.
Activa la whitelist de IPs si corres desde servidores con IP fija. Así, aunque tu secret se filtre, solo funcionará desde tus IPs.
Usa permisos mínimos. Dale a cada key solo lo que necesita.
Revoca las keys que no uses. Desde el panel, al instante.

CASK guarda solo un hash irreversible de tu secret, nunca el secret en sí. Si nuestra base de datos se viera comprometida, tus secrets seguirían protegidos.

Security

Your account's security depends on how you handle your credentials. Best practices:

Never share your secret. It's like a password. Anyone with it can read your data per the key's permissions.
Don't put it in public code (GitHub, front-end). Use environment variables.
Always use HTTPS. The API only responds over HTTPS, which encrypts your credentials in transit.
Enable the IP whitelist if you run from servers with a fixed IP. Even if your secret leaks, it only works from your IPs.
Use minimal permissions. Give each key only what it needs.
Revoke keys you don't use. From the panel, instantly.

CASK stores only an irreversible hash of your secret, never the secret itself. If our database were compromised, your secrets would remain protected.

Permisos

Cada API key tiene permisos granulares. Eliges cuáles al crearla:

Permiso	Descripción	Habilita
`read_balances`	Leer saldos y direcciones	`/balances`, `/addresses`
`read_history`	Leer historial	(próximamente)
`read_contacts`	Leer directorio	`/contacts`
`read_swap`	Cotizar swaps y ver fees	`/fees`, `/swap/quote`, `/ping`

Si una key usa un endpoint sin el permiso, recibe 403 forbidden_scope.

Permissions

Each API key has granular permissions. You choose them when creating it:

Permission	Description	Enables
`read_balances`	Read balances and addresses	`/balances`, `/addresses`
`read_history`	Read history	(coming soon)
`read_contacts`	Read directory	`/contacts`
`read_swap`	Get swap quotes and fees	`/fees`, `/swap/quote`, `/ping`

If a key uses an endpoint without the permission, it gets 403 forbidden_scope.

GET/pingscope: read_swap

Verifica que tus credenciales funcionan y muestra los permisos de la key. Útil para probar la integración.

Verifies your credentials work and shows the key's permissions. Useful for testing your integration.

Response · 200

{
  "ok": true,
  "user": "tu_username",
  "permissions": ["read_balances", "read_swap"]
}

GET/balancesscope: read_balances

Devuelve las direcciones de tu cuenta en las cadenas soportadas (Ethereum, Bitcoin, Tron).

Returns your account's addresses on the supported chains (Ethereum, Bitcoin, Tron).

Response · 200

{
  "user": "tu_username",
  "accounts": [
    {"chain": "ethereum", "address": "0xfa40d7ce..."},
    {"chain": "bitcoin", "address": "bc1q5x8lw..."},
    {"chain": "tron", "address": "TUMCTujmt..."}
  ]
}

La dirección de Ethereum sirve para todos los tokens EVM (ETH, USDC, BNB, HYPE). La de Tron para USDT y TRX. La de Bitcoin para BTC.

The Ethereum address works for all EVM tokens (ETH, USDC, BNB, HYPE). The Tron one for USDT and TRX. The Bitcoin one for BTC.

GET/addressesscope: read_balances

Igual que /balances, pero las direcciones vienen como objeto indexado por cadena. Más cómodo para acceso directo.

Same as /balances, but addresses come as an object indexed by chain. More convenient for direct access.

Response · 200

{
  "addresses": {
    "ethereum": "0xfa40d7ce...",
    "bitcoin": "bc1q5x8lw...",
    "tron": "TUMCTujmt..."
  }
}

GET/contactsscope: read_contacts

Devuelve tu directorio de contactos, con las direcciones de cada uno.

Returns your contact directory, with each contact's addresses.

Response · 200

{
  "contacts": [
    {
      "tag": "Mama",
      "cask_username": null,
      "addresses": [
        {"label": "Binance", "address": "TAiVLi5F...", "chain": "tron"}
      ]
    }
  ]
}

GET/feesscope: read_swap

Devuelve la configuración de fees y límites de swap.

Returns the swap fee configuration and limits.

Response · 200

{
  "swap": {
    "fee_percent": 0.4,
    "min_usd": 100.0,
    "max_usd": 5000.0,
    "enabled": true
  }
}

Cotización de swap

El endpoint más importante para bots. Cotiza un swap en tiempo real, sin generar ninguna orden. Devuelve el monto neto final que recibirías, listo para computar, más el desglose.

Swap quote

The most important endpoint for bots. Quotes a swap in real time, without generating any order. Returns the net final amount you'd receive, ready to compute, plus the breakdown.

GET/swap/quotescope: read_swap

Parámetros

Parámetro	Descripción	Ej.
`from`	Símbolo de origen	USDC
`from_net`	Red de origen	base
`to`	Símbolo de destino	ETH
`to_net`	Red de destino	base
`amount`	Cantidad de origen	100

Pares soportados: BNB/bsc, BTC/btc, DOGE/doge, ETH/base, ETH/eth, SOL/sol, TRX/tron, USDC/base, USDC/sol, USDT/sol, USDT/tron, XRP/xrp. Incluye cross-chain.

Parameters

Parameter	Description	Ex.
`from`	Source symbol	USDC
`from_net`	Source network	base
`to`	Destination symbol	ETH
`to_net`	Destination network	base
`amount`	Source amount	100

Supported pairs: BNB/bsc, BTC/btc, DOGE/doge, ETH/base, ETH/eth, SOL/sol, TRX/tron, USDC/base, USDC/sol, USDT/sol, USDT/tron, XRP/xrp. Includes cross-chain.

Request

GET /api/v1/swap/quote?from=USDC&from_net=base&to=ETH&to_net=base&amount=100

Response · 200

{
  "ok": true,
  "from": {"symbol": "USDC", "network": "base", "amount": 100.0},
  "to": {
    "symbol": "ETH", "network": "base",
    "amount": 0.061411,        // neto final
    "amount_min": 0.061104     // minimo con slippage
  },
  "rate": 0.00061411,          // 1 USDC = X ETH
  "breakdown": {
    "input_amount": 100.0,
    "cask_fee_percent": 0.4,
    "cask_fee_active": true,
    "slippage_percent": 0.5,
    "provider": "near_intents"
  },
  "time_estimate_sec": 37,
  "is_estimate": true
}

to.amount es el monto neto final (ya con fee y slippage). Es el número que usas para computar. rate es el precio unitario. breakdown tiene el desglose del fee.

to.amount is the net final amount (with fee and slippage). It's the number you use to compute. rate is the unit price. breakdown has the fee breakdown.

Esta cotización no genera ninguna orden ni compromete fondos. Podés llamarla las veces que quieras. La ejecución real se hace desde el wallet.

This quote does not generate any order or commit funds. You can call it as many times as you want. Actual execution is done from the wallet.

Códigos de error

Todos los errores devuelven un JSON con error (mensaje) y code (identificador).

HTTP	Código	Significado
401	`missing_auth`	Faltan los headers de autenticación
401	`invalid_key`	Key inexistente, revocada o expirada
401	`bad_secret`	El secret no coincide
403	`ip_forbidden`	Tu IP no está en la whitelist
403	`forbidden_scope`	La key no tiene el permiso
429	`rate_limited`	Superaste el límite de peticiones
400	`bad_pair`	Par de swap no soportado
400	`missing_params`	Faltan parámetros
503	`provider_down`	Proveedor de swap no disponible

Error codes

All errors return JSON with error (message) and code (identifier).

HTTP	Code	Meaning
401	`missing_auth`	Missing authentication headers
401	`invalid_key`	Key nonexistent, revoked, or expired
401	`bad_secret`	The secret doesn't match
403	`ip_forbidden`	Your IP is not in the whitelist
403	`forbidden_scope`	The key lacks the permission
429	`rate_limited`	You exceeded the request limit
400	`bad_pair`	Swap pair not supported
400	`missing_params`	Missing parameters
503	`provider_down`	Swap provider unavailable

Límites de uso

Rate limit: 120 peticiones por minuto por cada API key. Si lo superás, recibís 429 rate_limited. Espera un momento antes de reintentar.

Rate limits

Rate limit: 120 requests per minute per API key. If you exceed it, you receive 429 rate_limited. Wait a moment before retrying.

Ejemplos de código

El mismo swap quote (100 USDC → ETH) en varios lenguajes:

Code examples

The same swap quote (100 USDC → ETH) in several languages:

Python

import requests

BASE = "https://cask.network/api/v1"
HEADERS = {
    "X-Api-Key": "cask_pk_tu_key",
    "X-Api-Secret": "cask_sk_tu_secret",
}

params = {
    "from": "USDC", "from_net": "base",
    "to": "ETH", "to_net": "base",
    "amount": "100",
}
r = requests.get(f"{BASE}/swap/quote", headers=HEADERS, params=params)
quote = r.json()
print(f"Recibirias: {quote['to']['amount']} ETH")

JavaScript / Node.js

const BASE = "https://cask.network/api/v1";
const HEADERS = {
  "X-Api-Key": "cask_pk_tu_key",
  "X-Api-Secret": "cask_sk_tu_secret",
};

const params = new URLSearchParams({
  from: "USDC", from_net: "base",
  to: "ETH", to_net: "base", amount: "100",
});
const r = await fetch(`${BASE}/swap/quote?${params}`, { headers: HEADERS });
const quote = await r.json();
console.log(`Recibirias: ${quote.to.amount} ETH`);

PHP

$base = "https://cask.network/api/v1";
$headers = [
    "X-Api-Key: cask_pk_tu_key",
    "X-Api-Secret: cask_sk_tu_secret",
];
$params = http_build_query([
    "from" => "USDC", "from_net" => "base",
    "to" => "ETH", "to_net" => "base", "amount" => "100",
]);
$ch = curl_init("$base/swap/quote?$params");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$quote = json_decode(curl_exec($ch), true);
echo "Recibirias: " . $quote["to"]["amount"] . " ETH";

url := "https://cask.network/api/v1/swap/quote?from=USDC&from_net=base&to=ETH&to_net=base&amount=100"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("X-Api-Key", "cask_pk_tu_key")
req.Header.Set("X-Api-Secret", "cask_sk_tu_secret")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var quote map[string]interface{}
json.NewDecoder(resp.Body).Decode("e)
to := quote["to"].(map[string]interface{})
fmt.Printf("Recibirias: %v ETH\n", to["amount"])

Ruby

require "net/http"
require "json"

uri = URI("https://cask.network/api/v1/swap/quote")
uri.query = URI.encode_www_form({
  from: "USDC", from_net: "base",
  to: "ETH", to_net: "base", amount: "100",
})
req = Net::HTTP::Get.new(uri)
req["X-Api-Key"] = "cask_pk_tu_key"
req["X-Api-Secret"] = "cask_sk_tu_secret"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
quote = JSON.parse(res.body)
puts "Recibirias: #{quote['to']['amount']} ETH"

curl

curl "https://cask.network/api/v1/swap/quote?from=USDC&from_net=base&to=ETH&to_net=base&amount=100" \
  -H "X-Api-Key: cask_pk_tu_key" \
  -H "X-Api-Secret: cask_sk_tu_secret"

CASK API v1 · Fase 1 (lectura)Phase 1 (read-only)