API contracts
Source of truth for REST endpoints used by @fractalshq/sync. Pseudocode below mirrors the structures we expose over REST and gRPC; schemas will ship as OpenAPI/ts-rest files once the SDK is public. This contract is experimental and will change as we keep hardening Sync, but the shapes here should give you a clear idea of what the API exposes.
POST /sync/v1/distributions
Request body:
{
"cohortId": "ecosystem-weekly",
"mint": "GEODs9nC6HvZ4a3we8qC3dKpVt7y2SN8Wg4uLv3rWdXH",
"admin": "devonsolana.sol",
"schedule": {
"startVestingTs": 1763056306,
"endVestingTs": 1763142706,
"clawbackStartTs": 1763229106
},
"memo": "fractals:distribution:23:fund",
"pricingHint": {
"solUsd": 110.0
}
}Response:
{
"transaction": "base64-encoded v0 tx",
"summary": {
"distributionId": "dist_23",
"cohortLabel": "Ecosystem weekly",
"estimatedCost": {
"lamports": 4600560,
"usd": 0.51
},
"merkle": {
"root": "0xf2d956...",
"maxTotalClaim": "1635000000000",
"maxNumNodes": 5
}
}
}The transaction string is base64-encoded v0 and ready to hand to any wallet adapter (Ledger, Phantom, Backpack, server signer, etc.) without additional assembly.
POST /sync/v1/distributions/{id}/claims
Request body:
{
"wallet": "CKvGMtMBuCNWiUHpf4XCY5uaXzE5EaELJ6KwbHXtWGVd",
"commitment": "confirmed"
}Response:
{
"transaction": "base64-encoded claim tx",
"expectedAmount": "10097777",
"token": {
"mint": "XNET",
"decimals": 8
},
"subsidy": {
"usd": 0.5,
"note": "Claim fees covered by Sync"
}
}Just like distribution creation, the base64 transaction here can be signed by any wallet (Ledger or Phantom included) as-is.
GET /sync/v1/cohorts
Query params:
/sync/v1/cohorts?label=DePIN&limit=20Response:
{
"items": [
{
"id": "cohort_depin_validators",
"label": "DePIN validators",
"size": 143,
"lastUpdatedAt": "2025-01-03T18:22:11.000Z"
}
],
"nextCursor": null
}Standard errors share the shape:
{
"error": {
"code": "COHORT_NOT_FOUND",
"message": "Cohort cohort_depin_validators does not exist",
"retryable": false
}
}Last updated on