{"openapi":"3.1.0","info":{"title":"AlgoReclaim API","version":"1.1.0","summary":"Non-custodial Algorand minimum-balance recovery API","description":"Scan public Algorand accounts, prepare server-revalidated and simulated unsigned atomic groups, relay externally signed groups, and independently verify confirmation. The API never accepts mnemonics, seed phrases, private keys, or wallet credentials."},"externalDocs":{"description":"Developer guide, cURL examples, CLI, and signing boundary","url":"https://algoreclaim.com/developers"},"servers":[{"url":"https://algoreclaim.com","description":"AlgoReclaim production"}],"tags":[{"name":"Service","description":"Availability and feature status"},{"name":"Reclaim","description":"The non-custodial reclaim workflow"}],"paths":{"/api/health":{"get":{"operationId":"getHealth","tags":["Service"],"summary":"Check service and MainNet connectivity","responses":{"200":{"description":"Service and MainNet dependency are healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"The Algorand network dependency is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/api/scan":{"post":{"operationId":"scanAccount","tags":["Reclaim"],"summary":"Scan a public Algorand address","description":"Reads current account state and classifies zero-balance ASA holdings. Application Local State is returned for manual review and is never automatically selected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"},"example":{"address":"EAYSXYZKSHQGSITTERES43JMADDZB2WW4LCGHCCX6S7GI6ZPEVU3K2DOIE","network":"mainnet"}}}},"responses":{"200":{"description":"Exact account state and MBR classification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResult"}}}},"400":{"description":"Malformed or invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Account not found or requested network unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Account exceeds the configured complete-scan limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after the number of seconds in Retry-After","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/prepare":{"post":{"operationId":"prepareReclaim","tags":["Reclaim"],"summary":"Revalidate, build, and simulate unsigned reclaim groups","description":"Rescans all selections immediately before building atomic groups. Every app selection must also appear in acknowledgedAppIds. The returned preparation token expires after ten minutes and is bound to the wallet, network, group, and exact transaction IDs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareRequest"},"example":{"address":"EAYSXYZKSHQGSITTERES43JMADDZB2WW4LCGHCCX6S7GI6ZPEVU3K2DOIE","network":"mainnet","selections":[{"kind":"asa","id":"123456"}],"acknowledgedAppIds":[]}}}},"responses":{"200":{"description":"Base64 unsigned transaction groups and preparation tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareResult"}}}},"400":{"description":"Malformed or invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"On-chain state changed, a selection became unsafe, or simulation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after the number of seconds in Retry-After","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Transaction preparation is disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/submit":{"post":{"operationId":"submitSignedGroup","tags":["Reclaim"],"summary":"Validate and relay an externally signed reclaim group","description":"Accepts only signed transaction bytes—not signing keys. The service decodes every transaction and rejects any group that differs from the prepared transaction IDs, wallet, network, receivers, amounts, atomic group, or allowed reclaim operations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitRequest"}}}},"responses":{"200":{"description":"The exact signed group was accepted by Algod","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitResult"}}}},"400":{"description":"Malformed or invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after the number of seconds in Retry-After","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Transaction relay is disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/receipt":{"post":{"operationId":"verifyReceipt","tags":["Reclaim"],"summary":"Verify group confirmation through Indexer","description":"The preparation token is validated before Indexer lookup. A 202 response is a valid pending state and can be retried with the same body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptRequest"}}}},"responses":{"200":{"description":"Confirmed and independently verified group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifiedReceipt"}}}},"202":{"description":"The group is not yet visible in Indexer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingReceipt"}}}},"400":{"description":"Malformed or invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The receipt does not match the prepared or on-chain group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; retry after the number of seconds in Retry-After","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Address":{"type":"string","pattern":"^[A-Z2-7]{58}$","example":"EAYSXYZKSHQGSITTERES43JMADDZB2WW4LCGHCCX6S7GI6ZPEVU3K2DOIE"},"Network":{"type":"string","enum":["mainnet","testnet"],"default":"mainnet"},"IntegerString":{"type":"string","pattern":"^\\d+$","example":"100000"},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"Health":{"type":"object","required":["status","service","features","mainnet","latencyMs","timestamp"],"properties":{"status":{"type":"string","enum":["ok","degraded"]},"service":{"const":"algoreclaim"},"features":{"type":"object","required":["reclaim","feeCollection","referrals"],"properties":{"reclaim":{"enum":["enabled","scan-only"]},"feeCollection":{"enum":["enabled","disabled"]},"referrals":{"enum":["enabled","disabled"]}}},"mainnet":{"type":"object","required":["status"],"properties":{"status":{"enum":["ok","unavailable"]},"lastRound":{"$ref":"#/components/schemas/IntegerString"}}},"latencyMs":{"type":"integer","minimum":0},"timestamp":{"type":"string","format":"date-time"}}},"ScanRequest":{"type":"object","additionalProperties":false,"required":["address"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"network":{"$ref":"#/components/schemas/Network"}}},"AsaCandidate":{"type":"object","required":["kind","id","name","unitName","balance","decimals","frozen","creator","isCreator","isNft","mbrMicroAlgos","classification","reason"],"properties":{"kind":{"const":"asa"},"id":{"$ref":"#/components/schemas/IntegerString"},"name":{"type":"string"},"unitName":{"type":"string"},"balance":{"$ref":"#/components/schemas/IntegerString"},"decimals":{"type":"integer","minimum":0},"frozen":{"type":"boolean"},"creator":{"type":"string"},"isCreator":{"type":"boolean"},"isNft":{"type":"boolean"},"deleted":{"type":"boolean"},"mbrMicroAlgos":{"$ref":"#/components/schemas/IntegerString"},"classification":{"enum":["safe","blocked"]},"reason":{"type":"string"}}},"AppCandidate":{"type":"object","required":["kind","id","uints","byteSlices","mbrMicroAlgos","classification","deleted","risk"],"properties":{"kind":{"const":"app"},"id":{"$ref":"#/components/schemas/IntegerString"},"uints":{"type":"integer","minimum":0},"byteSlices":{"type":"integer","minimum":0},"mbrMicroAlgos":{"$ref":"#/components/schemas/IntegerString"},"classification":{"const":"manual"},"deleted":{"type":"boolean"},"risk":{"type":"string"}}},"ScanResult":{"type":"object","required":["address","network","round","totalBalanceMicroAlgos","currentMbrMicroAlgos","availableMicroAlgos","grossReleasableMicroAlgos","defaultSelectedMicroAlgos","belowRecommendedThreshold","assets","apps","scannedAt"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"network":{"$ref":"#/components/schemas/Network"},"round":{"$ref":"#/components/schemas/IntegerString"},"totalBalanceMicroAlgos":{"$ref":"#/components/schemas/IntegerString"},"currentMbrMicroAlgos":{"$ref":"#/components/schemas/IntegerString"},"availableMicroAlgos":{"$ref":"#/components/schemas/IntegerString"},"grossReleasableMicroAlgos":{"$ref":"#/components/schemas/IntegerString"},"defaultSelectedMicroAlgos":{"$ref":"#/components/schemas/IntegerString"},"belowRecommendedThreshold":{"type":"boolean"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/AsaCandidate"}},"apps":{"type":"array","items":{"$ref":"#/components/schemas/AppCandidate"}},"scannedAt":{"type":"string","format":"date-time"}}},"Selection":{"type":"object","additionalProperties":false,"required":["kind","id"],"properties":{"kind":{"enum":["asa","app"]},"id":{"$ref":"#/components/schemas/IntegerString"}}},"PrepareRequest":{"type":"object","additionalProperties":false,"required":["address","selections"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"network":{"$ref":"#/components/schemas/Network"},"selections":{"type":"array","minItems":1,"maxItems":2000,"items":{"$ref":"#/components/schemas/Selection"}},"acknowledgedAppIds":{"type":"array","maxItems":2000,"default":[],"items":{"$ref":"#/components/schemas/IntegerString"}}}},"PreparedGroup":{"type":"object","required":["unsignedTransactions","preparationToken","labels","grossRelease","platformFee","referralFee","simulatedAtRound"],"properties":{"unsignedTransactions":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","contentEncoding":"base64"}},"preparationToken":{"type":"string","description":"Ten-minute signed capability bound to this exact group."},"labels":{"type":"array","items":{"type":"string"}},"grossRelease":{"$ref":"#/components/schemas/IntegerString"},"platformFee":{"$ref":"#/components/schemas/IntegerString"},"referralFee":{"$ref":"#/components/schemas/IntegerString"},"simulatedAtRound":{"$ref":"#/components/schemas/IntegerString"}}},"PrepareResult":{"type":"object","required":["groups","feeEnabled"],"properties":{"groups":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/PreparedGroup"}},"referrer":{"$ref":"#/components/schemas/Address"},"feeEnabled":{"type":"boolean"}}},"SubmitRequest":{"type":"object","additionalProperties":false,"required":["address","network","signedTransactions","preparationToken"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"network":{"$ref":"#/components/schemas/Network"},"signedTransactions":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","contentEncoding":"base64","maxLength":8192}},"preparationToken":{"type":"string","maxLength":16384}}},"SubmitResult":{"type":"object","required":["txId","transactionIds","groupId","explorerUrl"],"properties":{"txId":{"type":"string"},"transactionIds":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","pattern":"^[A-Z2-7]{52}$"}},"groupId":{"type":"string","contentEncoding":"base64"},"explorerUrl":{"type":"string","format":"uri"}}},"ReceiptRequest":{"type":"object","additionalProperties":false,"required":["address","network","transactionIds","preparationToken"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"network":{"$ref":"#/components/schemas/Network"},"transactionIds":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","pattern":"^[A-Z2-7]{52}$"}},"preparationToken":{"type":"string","maxLength":16384}}},"PendingReceipt":{"type":"object","required":["verified","pending","transactionIds"],"properties":{"verified":{"const":false},"pending":{"const":true},"transactionIds":{"type":"array","items":{"type":"string"}}}},"VerifiedReceipt":{"type":"object","required":["verified","pending","group","confirmedRound","transactions"],"properties":{"verified":{"const":true},"pending":{"const":false},"group":{"type":"string"},"confirmedRound":{"$ref":"#/components/schemas/IntegerString"},"transactions":{"type":"array","items":{"type":"object","required":["id","explorerUrl"],"properties":{"id":{"type":"string","pattern":"^[A-Z2-7]{52}$"},"explorerUrl":{"type":"string","format":"uri"}}}}}}}}}