API reference
Send envelopes
Submit sealed message envelopes to the relay. The API key’s address is the sender. Bodies must already be encrypted — this route only forwards opaque ciphertext fields. To read incoming messages, see Receive & ack.
POST/api/v1/envelopes
Body shapes
Accepts any of:
- A single envelope object
- A JSON array of envelopes
{ "envelopes": [ … ] }
Envelope fields
| Field | Type | Required |
|---|---|---|
| toAddress | string | yes — recipient wallet |
| ciphertext | string | yes — base64 sealed box |
| ephemeralPublicKey | string | yes — hex X25519 eph pub |
| nonce | string | yes — base64 IV |
| recipientDeviceKey | string | no — target device pub |
| asRequest | boolean | no — route via consent/requests |
Envelopes are validated for real sealing before they route:
ephemeralPublicKey must be a 32-byte X25519 key in hex, nonce a 12-byte AES-GCM IV in base64, and ciphertext base64 of sealed bytes (≥ plaintext + 16-byte GCM tag). Base64-wrapped plaintext is rejected with a 400 — encrypt with the seal() recipe from the Device keys page.Examples
bash
curl https://api.sealedlabs.net/api/v1/envelopes \
-H "Authorization: Bearer $SEALED_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"toAddress": "0x…",
"ciphertext": "…",
"ephemeralPublicKey": "…",
"nonce": "…",
"asRequest": true
}'Single-envelope responses return one result object. Batch requests return
{ "results": [ … ] }.Try it
Try it — submit an envelope
POST /api/v1/envelopesYou must seal the payload on your device first. This API never accepts plaintext.