API Dokumentace

Kompletní reference pro API Obolus s podporou x402.

Začínáme

Obolus poskytuje bankovní data API s platbou za požadavek. Žádné předplatné, žádné kvóty - platíte pouze za to, co používáte.

Rychlý start

  1. Zvolte si adresu peněženky (jakýkoli jedinečný řetězec)
  2. Dobijte si peněženku kredity
  3. Provádějte API požadavky s vaší peněženkou jako bearer tokenem
# 1. Dobití kreditů
curl -X POST http://localhost:3000/api/wallet/topup \
  -H "Content-Type: application/json" \
  -d '{"address": "moje-penezenka", "amount": 100}'

# 2. Kontrola zůstatku
curl -H "Authorization: Bearer moje-penezenka" \
  http://localhost:3000/api/wallet/balance

# 3. Placené API volání
curl -H "Authorization: Bearer moje-penezenka" \
  http://localhost:3000/api/banking/rates

Autentizace

Všechny API požadavky vyžadují Bearer token s adresou vaší peněženky:

Authorization: Bearer <adresa-penezenky>

Adresa vaší peněženky slouží jako API klíč. Není nutná žádná registrace - stačí si vybrat jedinečný identifikátor a začít ho používat.

Ceník

Každý API endpoint má fixní cenu v kreditech. 1 kredit = ... Kč

Endpoint Cena Popis
/api/banking/rates 1 kredit Všechny směnné kurzy
/api/banking/rates/:pair 1 kredit Konkrétní měnový pár
/api/banking/swift/:bic 5 kreditů Vyhledání SWIFT/BIC
/api/banking/iban/validate 2 kredity Validace IBAN
/api/banking/holidays/:cc 1 kredit Bankovní svátky podle země
/api/banking/convert 1 kredit Převod měn
/api/banking/banks/:country 3 kredity Seznam bank podle země
/api/banking/sepa/:country 2 kredity Informace o SEPA zóně
/api/banking/currency/:code 1 kredit Metadata měny

Endpointy peněženky

Správa vašeho kreditového zůstatku. Tyto endpointy jsou zdarma.

GET /api/wallet/balance

Získání aktuálního kreditového zůstatku.

Hlavičky: Authorization: Bearer <adresa>

{
  "address": "moje-penezenka",
  "credits": 95,
  "creditValue": "2,19 Kč"
}
GET /api/wallet/transactions

Získání historie transakcí.

Hlavičky: Authorization: Bearer <adresa>

{
  "transactions": [
    {
      "id": "tx_abc123",
      "amount": 100,
      "description": "Ruční dobití",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "tx_def456",
      "amount": -1,
      "description": "API: /api/banking/rates",
      "created_at": "2024-01-15T10:35:00Z"
    }
  ]
}
POST /api/wallet/topup

Přidání kreditů do peněženky. (Dev/testovací režim - bez platby)

Tělo požadavku:

{
  "address": "moje-penezenka",
  "amount": 100
}

Odpověď:

{
  "success": true,
  "transaction": { "id": "tx_...", "amount": 100, ... },
  "newBalance": 100
}

Bankovní endpointy

Prémiová bankovní data. Tyto endpointy vyžadují platbu přes protokol x402.

GET /api/banking/rates 1 kredit

Získání všech dostupných směnných kurzů.

{
  "base": "USD",
  "timestamp": "2024-01-15T10:30:00Z",
  "rates": {
    "EUR": 0.92,
    "GBP": 0.79,
    "JPY": 148.50,
    ...
  }
}
GET /api/banking/rates/:pair 1 kredit

Získání kurzu pro konkrétní měnový pár (např. USD-EUR).

{
  "pair": "USD-EUR",
  "from": "USD",
  "to": "EUR",
  "rate": 0.92,
  "timestamp": "2024-01-15T10:30:00Z"
}
GET /api/banking/swift/:bic 5 kreditů

Vyhledání údajů o bance podle SWIFT/BIC kódu.

{
  "bic": "DEUTDEFF",
  "bank": "Deutsche Bank AG",
  "branch": "Frankfurt Main",
  "city": "Frankfurt",
  "country": "Německo",
  "countryCode": "DE"
}
POST /api/banking/iban/validate 2 kredity

Validace IBAN a extrakce detailů.

Tělo požadavku:

{ "iban": "DE89370400440532013000" }

Odpověď:

{
  "valid": true,
  "iban": "DE89370400440532013000",
  "country": "Německo",
  "countryCode": "DE",
  "checkDigits": "89",
  "bban": "370400440532013000"
}
GET /api/banking/holidays/:countryCode 1 kredit

Získání bankovních svátků pro danou zemi (např. CZ, SK, DE).

{
  "country": "Česká republika",
  "countryCode": "CZ",
  "year": 2024,
  "holidays": [
    { "date": "2024-01-01", "name": "Nový rok" },
    { "date": "2024-05-01", "name": "Svátek práce" },
    ...
  ]
}
POST /api/banking/convert 1 kredit

Převod částky mezi měnami.

Tělo požadavku:

{
  "from": "USD",
  "to": "CZK",
  "amount": 100
}

Odpověď:

{
  "from": "USD",
  "to": "CZK",
  "amount": 100,
  "result": 2315.00,
  "rate": 23.15,
  "timestamp": "2024-01-15T10:30:00Z"
}
GET /api/banking/banks/:country 3 kredity

Získání seznamu bank pro danou zemi (např. CZ, SK, DE).

{
  "country": "CZ",
  "count": 3,
  "banks": [
    {
      "bic": "KOMBCZPP",
      "bank": "Komerční banka",
      "city": "Praha",
      "address": "Na Příkopě 33"
    },
    {
      "bic": "CABORCZP",
      "bank": "Česká spořitelna",
      "city": "Praha",
      "address": "Olbrachtova 1929/62"
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}
GET /api/banking/sepa/:country 2 kredity

Získání informací o SEPA zóně pro danou zemi.

{
  "country": "CZ",
  "inSepa": true,
  "name": "Česká republika",
  "currency": "CZK",
  "eurozone": false,
  "sepaSchemes": ["SCT", "SDD"],
  "schemeDescriptions": {
    "SCT": "SEPA Credit Transfer",
    "SDD": "SEPA Direct Debit"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
GET /api/banking/currency/:code 1 kredit

Získání metadat měny (např. CZK, EUR, USD).

{
  "code": "CZK",
  "name": "Česká koruna",
  "symbol": "Kč",
  "decimals": 2,
  "countries": ["Česká republika"],
  "formatting": {
    "symbolPosition": "after",
    "thousandsSeparator": " ",
    "decimalSeparator": ","
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Zpracování chyb

API používá standardní HTTP stavové kódy:

Formát chybové odpovědi

{
  "error": "Typ chyby",
  "message": "Popis pro člověka"
}

Protokol x402

Když zavoláte placený endpoint bez dostatečného kreditu, obdržíte HTTP 402 odpověď:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": "Platba vyžadována",
  "message": "Tento endpoint vyžaduje 5 kreditů. Máte 2 kredity.",
  "payment": {
    "required": true,
    "amount": 5,
    "currency": "kredity",
    "endpoint": "/api/banking/swift/DEUTDEFF",
    "currentBalance": 2,
    "topupUrl": "/api/wallet/topup"
  }
}

Pro vyřešení:

  1. Zavolejte POST /api/wallet/topup pro přidání kreditů
  2. Opakujte původní požadavek

Výhody x402