Programs are stored on your account. Members convert on the public curve. The points ledger stays with the project.

DEVELOPERS

Turn your app's points into tokens with one call.

Your app keeps its own point system. Token Orbit prices points on a public curve and the NEAR contract pays the token. You make one API call; your member signs one transaction.

Quickstart

  1. Create a program and fund it in the console. On the program page, under the ledger, choose Create API key. The key is shown once.
  2. When a user wants to cash out, call convert from your server with their user id, NEAR account and an order ref.
  3. Send the user to the returned convertUrl. They connect their wallet and approve once. Tokens land in their wallet.
Try it: a quote, no side effects
curl "https://app.daocubator.org/api/v1/points/convert/500?user=discord:123&key=orb_xxxx_yyyy"

The convert call

POST /api/v1/points/convert/{points} does three things in order. It checks the program on chain has an open window. With ref, it credits the points to the user, once per ref. Then it returns a quote and the link where the user signs.

Request
curl -X POST "https://app.daocubator.org/api/v1/points/convert/500" \
  -H "Authorization: Bearer orb_xxxx_yyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "discord:123",
    "nearAccount": "alice.near",
    "ref": "cashout-8841",
    "delivery": "near"
  }'
FieldRequiredMeaning
pointsyes, in the pathWhole number, 1 to 999,999,999,999.
useryesYour id for the user, up to 128 characters.
nearAccountfirst timeThe user's NEAR account. Linked once, then remembered.
refto creditYour unique id for this cash-out. Retrying with the same ref never credits twice. Leave it out to spend points already in the ledger.
deliverynonear (default) pays the wallet. intents pays the user's NEAR Intents balance, for swaps or other chains.

Fields can go in the JSON body or the query string. The body wins.

Response 200
{
  "mode": "ready",
  "user": "discord:123",
  "nearAccount": "alice.near",
  "points": "500",
  "balance": "500",
  "credited": { "ref": "cashout-8841", "duplicate": false },
  "quote": {
    "contract": "orbit.example.near",
    "window": 0,
    "token": "token.example.near",
    "decimals": 18,
    "pointsUsed": "500",
    "pointsReturned": "0",
    "award": "905644044321329639889",
    "awardFormatted": "905.644044"
  },
  "convertUrl": "https://app.daocubator.org/convert/<program-id>?points=500"
}

The award is an estimate at the current point on the curve. The contract sets the final amount when the user signs, and earlier conversions in the window lower the rate. pointsReturned is what the window cannot take; those points stay in the user's balance.

Why the user signs. The contract pays only the account that submits the signed attestation. No server, including ours, can convert on a user's behalf or redirect their tokens.

Check the result later
curl "https://app.daocubator.org/api/v1/conversions?user=discord:123" \
  -H "Authorization: Bearer orb_xxxx_yyyy"
# status: reserved → submitted → settled (or owed, or expired and refunded)

Endpoints

All take your project key. Every response is JSON and never cached.

MethodPathWhat it does
GET/api/v1/points/convert/{points}?user=Quote a conversion. Checks the user, wallet and balance. Changes nothing.
POST/api/v1/points/convert/{points}Credit (with ref), link the wallet, and get the member's convert link.
POST/api/v1/pointsCredit or debit points for a user. Idempotent on ref.
GET/api/v1/points?user=A user's point balance and linked NEAR account.
POST/api/v1/membersLink a user to their NEAR account.
GET/api/v1/conversions?user=A user's recent conversions and their status.
GET/api/healthDatabase and contract reachability. No key needed.
Credit points as users earn them (optional)
curl -X POST "https://app.daocubator.org/api/v1/points" \
  -H "Authorization: Bearer orb_xxxx_yyyy" -H "Content-Type: application/json" \
  -d '{ "user": "discord:123", "points": 250, "ref": "quest-42", "nearAccount": "alice.near" }'

Errors

Errors return { "error": "<sentence>", "code": "<code>" }. Branch on the code; show the sentence.

CodeHTTPMeaning and fix
no_key, bad_key401Missing, wrong or revoked API key.
invalid400A parameter is missing or malformed. The message names it.
unknown_user404No such user yet. Pass ref to credit points in the same call.
no_wallet409The user has no NEAR account linked. Pass nearAccount.
insufficient_points409Balance is below the requested points. Pass ref to credit them.
closed, window_full409No conversion window is open, or the open one is used up.
unregistered, suspended409, 423The program is not on NEAR yet, or an admin paused it.
rate_limited429Over 120 convert calls a minute for this key.
rpc502NEAR RPC did not answer. Retry with backoff.

Keys and safety

  • Send the key as Authorization: Bearer orb_…. The ?key= form works for quick tests, but URLs end up in logs and browser history.
  • Call the API from your server only. A key in a web or mobile app can be copied and used to credit points.
  • We store only a hash of each key. Revoke a leaked key on the program page and create a new one.
  • Always send a ref when crediting. It makes retries safe after a timeout.
  • The contracts are open source and verifiable on chain: token-orbit-contracts.