Launch app

Documentation

Build on Nulo.

N°01Introduction

Nulo sells virtual cards, gift cards and mobile data for USDC on Solana. Everything you can do in the app is available through a REST API and a CLI - for you as the owner, and for agent keys with their own limits.

There is no identity check. An account is a Solana wallet; a request is signed by that wallet or by a key it issued. Prices are always quoted first, with the provider price and the Nulo fee as separate lines.

N°02Quickstart

Install the CLI, sign in with your wallet and price your first gift card.

terminal

$ npm i -g @nulo/cli
$ nulo login            # opens your wallet to sign once
$ nulo balance
248.60 USDC
$ nulo giftcard quote --country DE --brand games --amount 25
quote q_7f3c · 27.31 USDC · expires in 90s
$ nulo order q_7f3c

N°03Agents

An agent key spends from your balance and nothing else. You choose what it may buy, how much per order and in total, the amount above which it must wait for you, and when the key expires. Budgets count fees and orders still in flight. A key can never withdraw.

terminal

$ nulo agent create travel-booker \
    --scope esim,giftcard --budget 200 --per-order 40 \
    --approve-above 25 --expires 14d
key ak_•••• created · active for 14 days
$ nulo agent revoke travel-booker

N°04API

Base URL https://api.nulo.example. Authenticate with a bearer key; send an Idempotency-Key with every order so a retry never buys twice.

MethodPathWhat it does
POST/v1/quotesPrice a card, gift card or eSIM. Valid for 90 seconds.
POST/v1/ordersPlace an order from a quote. Idempotent by key.
GET/v1/orders/{id}Order status and delivery record.
GET/v1/cardsYour cards and their balances.
POST/v1/cards/{id}/revealShort-lived card details for one checkout.
GET/v1/catalog/giftcardsBrands and amounts by country.
GET/v1/catalog/esimPlans by country or region.
POST/v1/agentsCreate an agent key with scope and limits.
DELETE/v1/agents/{id}Revoke a key. Its next request is refused.

curl

curl https://api.nulo.example/v1/quotes \
  -H "Authorization: Bearer $NULO_KEY" \
  -d '{"product":"esim","country":"JP","plan":"10gb-30d"}'

N°05CLI

The CLI wraps the API one-to-one. Every command takes --json for scripts and agents.

nulo login

Sign in with your wallet

nulo balance

USDC available to spend

nulo card issue

Reloadable or prepaid

nulo giftcard quote

Price by country and brand

nulo esim plans

Plans for a destination

nulo agent create

Key with scope and limits

N°06Webhooks

Register a URL and receive order events as they happen: order.quoted, order.waiting_approval, order.delivered, order.failed. Each payload is signed; check the signature before you trust it.

order.delivered.json

{
  "type": "order.delivered",
  "order": "ord_0042",
  "product": "giftcard",
  "amount": "27.31",
  "currency": "USDC",
  "placed_by": "agent:travel-booker"
}