Agent API
Baskets
Read baskets and buy them.
A basket is a mix of up to 20 tokenized stocks and tokens, each with its share of a box price, that someone published on giftedstock.com/basket ↗. Buying one through the API makes gift boxes holding that mix at today's prices, sealed, in your own wallet. Making a basket is done on the site (Create a basket); the API buys them.
Read a basket
The API has no basket list. A basket is read from its page at https://www.giftedstock.com/basket/<code>. Every buy plan names what it buys in summary.basket: its code, name, link, maker, box price and mix (each token with its share). Show those to your user before you send. Check them against the basket's page if they did not pick it there.
Buy a basket
POST /tx/basket
{ "wallet": "0xYou", "skill": "1.3.0", "basket": "a1b2c", "quantity": 2, "payWith": "USDC" }| Field | Rule |
|---|---|
skill | Required: "1.3.0" or later. Without it the answer is needs_skill. |
basket | The basket's code (5 letters and digits) or its link https://www.giftedstock.com/basket/<code>. |
quantity | 1 to 100 boxes, 1 if left out. |
payWith | "USDC" (if left out) or "ETH". |
No other field is taken: the boxes always go to your own wallet. The fee and the router are ours.
- The plan is an exact USDC approval when one is needed, then the gift router's buy of that many boxes. It lasts 20 minutes.
- The fee is 2.5% on top: the gift contract's own fee and the app-fee share, which goes to the basket's maker (
summary.fee.app). When you made the basket yourself it goes to us. summary.basket.makerBatchis the maker's first gift with this basket's tag. verify.mjs checks onchain that the maker made it with the same tokens. That shows the wallet bought this basket, not that it made it: check the maker against the basket's page.- Each box's id is in the receipt's BoxMinted logs and in GET /gifts?wallet=. Buys show under the basket within minutes.
Refusals
| Code | Meaning |
|---|---|
| needs_skill | The request did not name skill 1.3.0. |
| bad_basket | Not a basket code or link. |
| no_basket (404) | No basket has this code. |
| basket_hidden (409) | The basket was taken down. Boxes already made still open. |
| price_moved (409) | The quote is more than 3% over the basket's price: build it again shortly. |
| not_buyable, token_not_allowed, no_price (409) | A token in the mix cannot be bought or boxed right now: try later. |
| insufficient_balance (409) | The wallet holds less than the buy needs. |
POST /tx/gift/open, described on Gift boxes.