Agent API
Gift boxes
Make gift boxes and claim them.
Gift boxes live on Base. Each box holds the same tokens, bought as the gift is made and paid in USDC or ETH. The boxes go to wallets you name or behind a link people claim from. The fee is 2.5% on top: the gift contract's own fee and the app-fee share, both named in summary.fee. The plan format is on How it works. For what a gift box is to people who get one, see What's a gift box?
Read gifts
GET /gifts?wallet={address}
A wallet's gift boxes and the gifts it made.
| Field | What it is |
|---|---|
received | Each box it holds: its id, gift, state, who sent it and their note. An opened box adds what it held. |
created | Each gift it made: direct (with each wallet and whether it opened) or a link (status, boxes left, claimed, taken back, claim times). |
pending | Tokens an opened box could not send at the time (a paused stock), waiting for withdrawPending on the gift contract. |
GET /gift/{batchId}
A link's public facts: open or not, boxes left, who may claim and when, who made it, its note and what each box holds. A gift sent straight to wallets has no link and answers not_a_link.
Make a gift
POST /tx/gift
{
"wallet": "0xYou",
"skill": "1.3.0",
"items": [{ "token": "NVDAc", "usd": "5" }, { "token": "cbBTC", "usd": "1" }],
"to": ["fren.base.eth", "0xF4E2…96B8"],
"payWith": "USDC",
"note": "happy birthday"
}| Field | Rule |
|---|---|
items | What each box holds: 1 to 20 tokens, each once, by ticker or address. Each takes usd (dollars, at most 2 places) or amount (in the token's units), at least $0.01 of each. Tokenized stocks, tokens such as cbBTC and BNKR, USDC and ETH. |
payWith | "USDC" or "ETH". The gift router buys each item as the gift is made and sends back what it does not spend. |
to | 1 to 100 wallets, addresses or names (name.base.eth, name.eth), one box each. A contract is refused: a box there could never be opened. |
link | Instead of to: a link people claim from (below). Give one of the two. |
note | Optional, up to 140 characters, shown with the gift. |
design | Optional: a design word (0x and 64 hex) or { box, ribbon, title, titleColour, stickers }. Colours as "#9ccc00", a title up to 16 characters, ribbon null for none. |
- The plan is an exact USDC approval when one is needed, then the router's buy. It lasts 20 minutes.
- A quote more than 3% over what the boxes hold at today's prices is refused with
price_moved: build it again shortly. - A wallet clearly short of the total is told first with
insufficient_balance(409).
Its own refusals: bad_items, unknown_token, below_minimum, bad_pay, bad_to, unknown_name, not_a_wallet, bad_note, bad_design, token_not_allowed, not_buyable, no_quote, no_eth_pool, price_moved and paused.
Make a gift link
{
"wallet": "0xYou",
"skill": "1.3.0",
"items": [{ "token": "TSLAc", "usd": "2" }],
"payWith": "USDC",
"link": { "boxes": 10, "who": "anyone", "linkKeyAddress": "0xFreshKeyAddress", "closesAt": "2026-12-31T23:59:00Z" }
}| link field | Rule |
|---|---|
boxes | 1 to 100,000. |
who | "anyone" with the link, "verified" (wallets verified on https://www.giftedstock.com/verify) or "list". |
list | With who "list": 1 to 100,000 wallet addresses. |
opensAt, closesAt | Unix seconds or ISO 8601. Claims open at once and close after 7 days unless you say otherwise; closesAt null means no end. |
linkKeyAddress | The address of a fresh key you made for this link (below). |
Step 1: Make a link key
Make a fresh key where you run (viem: generatePrivateKey()) and send only its address. Never your wallet's own key, never one used before, never funded: its private key goes into the share URL. A key used on Base or by another link is refused with link_key_used.
Step 2: Send the steps
In the last receipt, the gift contract's BatchCreated log (topic0 0x6780e18cae4367542f9523587cc962e780a8ac6a98b18b19dd3c48dc04a1c21b) holds the batchId as topics[1].
Step 3: Share the URL
https://www.giftedstock.com/gift?batch=<batchId>#k=<link key's private key>. Anyone holding it can claim while boxes are left.
Step 4: Take back what is left
Boxes nobody claimed stay yours until you take them back (below).
Link refusals besides the gift's own: bad_who, bad_list, bad_time, bad_link_key, link_key_used, verified_off and rate_limited (too many wallet lists from one address in a day).
Claim from a link
POST /tx/gift/claim
Two calls. From a share URL, the batchId is ?batch= and the link key is the private key after #k=. The link key stays where you run: it never goes to the API.
Step 1: Ask what to sign
Send { wallet, skill, batchId }. The answer has no steps: sign.typedData is an EIP-712 Claim naming your wallet. A wallet the link refuses (not verified, not on the list) is told now.
Step 2: Check and sign
primaryType is Claim, domain.chainId is 8453, domain.verifyingContract is the gift contract, message.claimer is your wallet and message.batchId is the link's. Sign it with the link key, not your wallet (viem: privateKeyToAccount(linkKey).signTypedData(typedData)).
Step 3: Get the claim
Send { wallet, skill, batchId, signature } and send the one step from your wallet. A verified-only link's approval inside lasts ten minutes.
Step 4: Find the box
It arrives sealed: its id is topics[2] of the Claimed log (0xc09f7b3c1c5b70bf6d30e485a4525d625d4723aed5d319376825446ef135c7ca).
Its refusals: no_gift, not_a_link, none_left, not_open_yet, claims_closed, already_claimed, not_verified (403), not_on_list (403), list_unknown, bad_signature and bad_link_signature.
Open gift boxes
POST /tx/gift/open
{ "wallet": "0xYou", "skill": "1.3.0", "ids": ["624"] }Up to 200 sealed gift boxes your wallet holds. What each holds goes to your wallet and the box stays as an opened record. Its refusals: no_box, not_holder (403) and not_sealed.
Take back a link's boxes
POST /tx/gift/take-back
{ "wallet": "0xYou", "skill": "1.3.0", "batchId": 12 }Only the link's maker. Every box nobody claimed comes back as its tokens and the link is done. A box claimed before the step is mined stays its claimer's. Its refusals: no_gift, not_a_link, not_creator (403) and none_left.