Quickstart
- 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.
- When a user wants to cash out, call convert from your server with their user id, NEAR account and an order ref.
- Send the user to the returned convertUrl. They connect their wallet and approve once. Tokens land in their wallet.
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.
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"
}'| Field | Required | Meaning |
|---|---|---|
| points | yes, in the path | Whole number, 1 to 999,999,999,999. |
| user | yes | Your id for the user, up to 128 characters. |
| nearAccount | first time | The user's NEAR account. Linked once, then remembered. |
| ref | to credit | Your unique id for this cash-out. Retrying with the same ref never credits twice. Leave it out to spend points already in the ledger. |
| delivery | no | near (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.
{
"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.
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.
| Method | Path | What 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/points | Credit 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/members | Link a user to their NEAR account. |
| GET | /api/v1/conversions?user= | A user's recent conversions and their status. |
| GET | /api/health | Database and contract reachability. No key needed. |
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.
| Code | HTTP | Meaning and fix |
|---|---|---|
| no_key, bad_key | 401 | Missing, wrong or revoked API key. |
| invalid | 400 | A parameter is missing or malformed. The message names it. |
| unknown_user | 404 | No such user yet. Pass ref to credit points in the same call. |
| no_wallet | 409 | The user has no NEAR account linked. Pass nearAccount. |
| insufficient_points | 409 | Balance is below the requested points. Pass ref to credit them. |
| closed, window_full | 409 | No conversion window is open, or the open one is used up. |
| unregistered, suspended | 409, 423 | The program is not on NEAR yet, or an admin paused it. |
| rate_limited | 429 | Over 120 convert calls a minute for this key. |
| rpc | 502 | NEAR 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.