ConsoleDocs
API reference

boleto.eth API

The boleto.eth REST API issues, verifies, and redeems on-chain tickets. Every endpoint accepts JSON, returns JSON, and is idempotent on idempotency_key.

Quickstart

Create an event, get an API key, mint your first ticket. The whole loop is three calls.

# 1. Create the event (signs USDC fee on activation)
curl -X POST https://api.boleto.eth/v1/events \
  -H "Authorization: Bearer sk_live_••••" \
  -d '{"artistSlug":"badbunny","eventSlug":"cdmx26","eventName":"Most Wanted",...}'

# 2. Activate it on-chain
curl -X POST https://api.boleto.eth/v1/events/<invoice_id>/confirm \
  -H "Authorization: Bearer sk_live_••••" \
  -d '{"txHash":"0x..."}'

# 3. Mint a ticket
curl -X POST https://api.boleto.eth/v1/tickets/mint \
  -H "Authorization: Bearer sk_live_••••" \
  -d '{"event_id":"evt_01HC9F","recipient":"0xA1c4...e8F2","seat":"A12",...}'

Authentication

Pass your secret key as a bearer token on every request. Keys begin with sk_test_ for sandbox andsk_live_ for production. Never embed a key in browser code — proxy requests through your backend.

Test vs live

Test keys exercise the full API surface but do not move USDC, register ENS, or mint on mainnet. Use them in CI. Live keys touch Ethereum mainnet — every request costs gas-equivalent infrastructure spend, so keep credentials tight.

Rate limits

100 req/s default per workspace. Bursts up to 500 are absorbed for ~3 seconds. Headers X-RateLimit-Limit,X-RateLimit-Remaining, and Retry-After are returned on every call. Email support@boleto.eth for higher limits.

Events

An Event is the unit of inventory. Creating one provisions an ENS subdomain (artist-slug.boleto.eth), deploys an ERC-721 collection, and configures royalties. Activation is a single USDC transfer on mainnet.

Tickets

A Ticket is an ERC-721 NFT minted under an event's ENS subdomain. Each ticket carries a unique seat assignment, an EIP-2981 royalty configuration, and a deterministic on-chain identifier.

Parameter
Type
Description
event_id
string
Identifier of the event to mint against.
recipient
string · 0x
Recipient wallet. Use your custodial address for white-label.
seat
string
Seat identifier — appears in the ENS subdomain.
section
string
Section name (e.g. "VIP").
row
string
Row identifier.
price_usdc
decimal
Settled price for the royalty calculation.

Royalties

Every ticket carries an EIP-2981 royalty record. Splits are set on event creation and enforced by all EIP-2981-compliant marketplaces (OpenSea, Magic Eden, Blur). Promoter royalty defaults to 1% — set per event 0–10%.

Webhooks

Every state transition (event activated, ticket minted, ticket transferred, ticket redeemed, royalty settled) emits a signed webhook. Requests carry an HMAC X-Boleto-Signature header so you can verify authenticity.

Issuance flow

Issuance is a two-step deploy + mint flow. Activate the event once (one USDC settlement), then mint tickets lazily as buyers complete checkout. Gas is paid by buyers via EIP-712 vouchers, or by you in custodial mode.

EIP-712 vouchers

A voucher is a signed message authorizing a single ticket mint. Sign with your operator key, hand the voucher to the buyer wallet, the buyer redeems on-chain. No counterfeits — duplicates revert at the contract.

Custodial wallets

White-label deployments mint into a custodial address you control, then transfer to the buyer when they connect. Buyers never see the word “wallet” on the happy path.

CSV import

Bulk-load seat inventory from a CSV. One row per seat. Required columns: seat_number, section,row, price_usdc. Optional: gate, tier, notes. 50,000 seats validate in under 30 seconds.

API · v1

The API is versioned in the URL path. Breaking changes ship under /v2; /v1 remains supported for 24 months after deprecation.

Webhook events

event.activated, ticket.minted, ticket.transferred, ticket.redeemed,royalty.settled, event.completed.

Errors

400 invalid_request
Missing or malformed parameter. Body included for inspection.
401 unauthenticated
Missing / invalid API key.
402 payment_required
Event invoice unpaid — finish the activation step first.
409 idempotency_conflict
Same idempotency_key used with different parameters.
422 inventory_exhausted
No seats left in the requested section.
429 rate_limited
Too many requests — back off using Retry-After.
500 internal_error
Server-side bug. Retry idempotently.

Changelog

v1.2.0 — 2026-05: ENS gateway upgrade, <400ms p95 mint latency.
v1.1.0 — 2026-04: EIP-2981 enforcement on Blur, CSV streaming import.
v1.0.0 — 2026-02: First production release on Ethereum mainnet.