Wallet API

Wallet API, wallet.solidus.network ’ü destekler; DID’e bağlı bir adres defteri, vasi tabanlı sosyal kurtarma ve bir kez doğruladığınız ve her yerde yeniden kullandığınız bir KYC kimlik bilgisine sahip çok zincirli bir cüzdan.

Tasarım gereği gözetimsiz: bu arka uç, imzasız işlemler oluşturur ve zaten istemci tarafında imzalanmış olanları aktarır. Bir kullanıcının tohum (seed) veya özel anahtarını hiçbir zaman almaz, tutmaz veya onunla imzalamaz — tüm kriptografik işlemler istemci tarafında gerçekleşir. Arka ucun kendi imzalayan anahtarı, yalnızca değer taşıyan bir hizmet/sponsor kimliğidir (DID yok), yalnızca yeni hesapları aktarmak ve sponsorlukla fonlamak için kullanılır.

swap, nfts ve buy, lansman için devre dışıdır — henüz zincir üzerinde bir DEX, NFT indeksleyicisi veya fiat giriş rampası yoktur ve bunlar için hiçbir rota bağlanmamıştır.

Temel URL: https://wallet.solidus.network/v1

Kimlik Doğrulama

POST /users/register veya POST /auth/session’daki OIDC devri tarafından basılan, kısa TTL’li bir JWT taşıyan bir oturum çerezi. Buna ihtiyaç duyan rotalar aşağıda authenticate olarak işaretlenmiştir; eksik veya süresi dolmuş bir oturumda 401 { "error": "Unauthorized" } döndürürler — bu özel kontrol, bu API’nin başka her yerinde kullanılan RFC 7807 hata biçimini atlar (aşağıdaki Hata biçimine bakın).

curl https://wallet.solidus.network/v1/users/me \
  -H "Cookie: solidus_wallet_session=<jwt>"

İki rota, kendi akışlarına özgü nedenlerle kasıtlı olarak oturum kimlik doğrulamasını atlar:

• POST /guardian/recovery/initiate ve POST /guardian/recovery/:requestId/finalize — kurtarma yapan kullanıcı, tanımı gereği oturumunu kaybetmiştir. Yeni anahtar zarfı artı toplanan vasi imzaları yetkidir; zincir bunları doğrular.
• GET /guardian/recovery/:requestId — tahmin edilemez istek UUID’siyle yoklanır; toplanan onaylar zaten zincire bağlı herkese açık imzalardır.
• POST /auth/session ayrıca X-Internal-Secret: <INTERNAL_API_SECRET> gerektirir — bu, cüzdan ön ucunun kendi OIDC geri çağırmasından sunucudan sunucuya bir çağrıdır, herkese açık bir rota değil.

Rota dizini

Kullanıcılar ve kimlik doğrulama

Kayıt

Tohum tabanlı akışın giriş noktası — istemci tarafında imzalanmış bir DidCreate’i (yeni cüzdan) aktarır veya mevcut bir DID’i (içe aktarma) bağlar, ardından oturum çerezini basar. Herkese açık.

curl -X POST https://wallet.solidus.network/v1/users/register \
  -H "content-type: application/json" \
  -d '{
    "signedDidCreate": "<client-signed DidCreate tx>",
    "addresses": [{ "chain": "solidus", "address": "3GfjBM7v6LZ1N5zp1b12gfpwCN8j", "derivation": "m/44'\''/9999'\''/0'\''/0/0" }],
    "displayName": "Ada"
  }'

signedDidCreate (oluşturma) veya did (içe aktarma)‘dan tam olarak biri gereklidir.

// Response 201
{ "id": "usr_...", "did": "did:solidus:testnet:..." }

Ben (Me)

curl https://wallet.solidus.network/v1/users/me -H "Cookie: solidus_wallet_session=<jwt>"

PATCH /users/me/settings, hideBalances ve/veya displayName’i günceller.

OIDC oturum devri

curl -X POST https://wallet.solidus.network/v1/auth/session \
  -H "X-Internal-Secret: <INTERNAL_API_SECRET>" -H "content-type: application/json" \
  -d '{"sub": "<verified OIDC subject>", "email": "[email protected]"}'

// Response 200 — no wallet linked yet
{ "needsOnboarding": true }

// Response 200 — linked
{ "id": "usr_...", "did": "did:solidus:testnet:...", "needsOnboarding": false }

Dizin

curl "https://wallet.solidus.network/v1/directory/resolve?did=did:solidus:testnet:..." \
  -H "Cookie: solidus_wallet_session=<jwt>"

Bir DID veya kolu (handle) kayıtlı bir cüzdan kullanıcısının Solidus alım adresine çözümler. did veya handle’dan tam olarak biri gereklidir.

Portföy

curl https://wallet.solidus.network/v1/wallet/addresses -H "Cookie: solidus_wallet_session=<jwt>"
curl https://wallet.solidus.network/v1/portfolio/assets -H "Cookie: solidus_wallet_session=<jwt>"
curl "https://wallet.solidus.network/v1/prices/slds/series?range=7d" -H "Cookie: solidus_wallet_session=<jwt>"

portfolio/assets, canlı zincir başına bakiyeleri artı USD değerlemesini döndürür. Fiyat serisi için assetId, slds, eth, btc’den biridir; range, 1d, 7d (varsayılan) veya 30d’dir.

İşlemler

Tüm akış hazırla-istemci-imzala-aktar’dır — sunucu hiçbir zaman bir anahtar görmez.

Hazırla

curl -X POST https://wallet.solidus.network/v1/transactions/prepare \
  -H "Cookie: solidus_wallet_session=<jwt>" -H "content-type: application/json" \
  -d '{"chain":"solidus","kind":"send","assetId":"slds","amount":25,"toAddress":"28gvczeVVVQjy6MpP4yexmd3xEsm"}'

kind, send, stake veya unstake’tir; toAddress, send için gereklidir. Tarayıcıda imzalamaya hazır, imzasız yükü artı çağıranın canlı zincir üstü nonce’unu döndürür.

Gönder

curl -X POST https://wallet.solidus.network/v1/transactions/send \
  -H "Cookie: solidus_wallet_session=<jwt>" -H "content-type: application/json" \
  -d '{
    "sender_pubkey": [ /* 32 bytes */ ],
    "nonce": 4,
    "payload": { "Transfer": { "to": "28gvczeVVVQjy6MpP4yexmd3xEsm", "amount": 2500000000 } },
    "signature": [ /* 64 bytes */ ]
  }'

Tam, zaten imzalanmış ChainTransaction — sunucu, sender_pubkey’in çağırana ait olduğunu kontrol eder, ardından onu olduğu gibi aktarır. Sunucu tarafında hiçbir zaman imzalanmaz veya yeniden imzalanmaz.

Listele

curl "https://wallet.solidus.network/v1/transactions?dateRange=30d&type=send" \
  -H "Cookie: solidus_wallet_session=<jwt>"

Sorgu parametreleri: dateRange (30d, 90d, 1y, varsayılan all), assetId (varsayılan all), type (varsayılan all, send, receive, stake, unstake, credential), search.

Stake Etme

curl -X POST https://wallet.solidus.network/v1/staking/stake \
  -H "Cookie: solidus_wallet_session=<jwt>" -H "content-type: application/json" \
  -d '{"sender_pubkey":[...],"nonce":5,"payload":{"Stake":{"amount":1000000000}},"signature":[...]}'

transactions/send ile aynı istemci tarafında imzalanmış aktarım deseni — stake/unstake gövdeleri bir {Stake:{amount}} / {Unstake:{amount}} yükü taşır. İmza, çağıranın kendi kayıtlı Solidus anahtarıyla eşleşmezse 403 döner.

curl https://wallet.solidus.network/v1/staking/network-stats

// Response 200 — measured live
{
  "totalStaked": 10000,
  "activeValidators": 5,
  "apy": { "value": 8.2, "sample": true },
  "validators": [
    { "address": "3GfjBM7v6LZ1N5zp1b12gfpwCN8j", "staked": 10000, "reputation": 1000, "active": true },
    { "address": "28gvczeVVVQjy6MpP4yexmd3xEsm", "staked": 0, "reputation": 0, "active": true }
  ]
}

apy.sample: true, açık bir etikettir — henüz zincir üzerinde bir APY kaynağı yoktur, bu bir yer tutucu değerdir, canlı bir hesaplama değil. totalStaked ve activeValidators, gerçek, canlı bir solidus_getValidators çağrısından gelir.

Vasi — sosyal kurtarma

DID-vasi tabanlı sosyal kurtarma: vasileri davet edin, imzalarını toplayın, kayıp bir anahtarı kurtarın.

curl -X POST https://wallet.solidus.network/v1/guardian/invite \
  -H "Cookie: solidus_wallet_session=<jwt>" -H "content-type: application/json" \
  -d '{"guardianEmail": "[email protected]", "guardianName": "Bea"}'

guardianDid veya guardianEmail’den en az biri gereklidir — yalnızca e-posta ile bir davetin, vasi kabul edene kadar DID’i yoktur. POST /guardian/recovery/initiate, subjectDid ve newPublicKey gerektirir; POST /guardian/recovery/:requestId/approve, kanonik kurtarma mesajı üzerinde 64 baytlık bir Ed25519 signature gerektirir.

Kimlik Bilgileri

curl https://wallet.solidus.network/v1/credentials -H "Cookie: solidus_wallet_session=<jwt>"

Bir credentials_cache’i okur, her satırın durumunu verify’a karşı en iyi çabayla yeniler — boş bir önbellek [] döndürür, kimlik bilgileri hiçbir zaman uydurulmaz.

curl -X POST https://wallet.solidus.network/v1/oid4vci/redeem \
  -H "Cookie: solidus_wallet_session=<jwt>" -H "content-type: application/json" \
  -d '{"credentialOffer": "<scanned OID4VCI credential_offer URL or JSON>"}'

Taranmış bir teklif için verify.solidus.network’e karşı OID4VCI ön yetkilendirilmiş kod akışını sunucudan sunucuya çalıştırır, ardından düzenlenen kimlik bilgisini önbelleğe alır. txCode, hibesi bir PIN taşıyan teklifler için isteğe bağlıdır (OID4VCI §3.5).

Adres Defteri

curl https://wallet.solidus.network/v1/address-book -H "Cookie: solidus_wallet_session=<jwt>"
curl -X POST https://wallet.solidus.network/v1/address-book \
  -H "Cookie: solidus_wallet_session=<jwt>" -H "content-type: application/json" \
  -d '{"name":"Bea","did":"did:solidus:testnet:...","addresses":[{"chain":"solidus","address":"28gvczeVVVQjy6MpP4yexmd3xEsm"}]}'
curl -X DELETE https://wallet.solidus.network/v1/address-book/<id> -H "Cookie: solidus_wallet_session=<jwt>"

Sağlık

curl https://wallet.solidus.network/v1/health

// Response 200 — measured live
{
  "status": "ok",
  "service": "wallet-backend",
  "build": { "commit": "36cdec1...", "builtAt": "2026-07-16T00:40:15.183Z" },
  "timestamp": "2026-07-29T11:25:13.108Z"
}

Not: wallet.solidus.network/health (/v1 olmadan), arka ucu değil, Next.js ön ucunu çözümler — arka ucun kendi sağlık kontrolü için /v1/health kullanın.

Hata biçimi

Doğrulama ve iş mantığı hataları (badRequest, forbidden vb.), her Solidus arka ucunda kullanılan aynı şekil olan RFC 7807 Problem Details’ı izler:

{
  "type": "https://solidus.network/errors/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "toAddress is required for a send transaction",
  "instance": "/v1/transactions/prepare"
}

authenticate dekoratöründen gelen oturum kimlik doğrulama hataları tek istisnadır — Problem Details şekli değil, düz bir 401 { "error": "Unauthorized" }.