API Reference

The Web3Card API is a REST API over HTTPS with JSON request and response bodies.

API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

Base URL

https://api.web3card.dev/v1

Authentication

All partner endpoints require your API key as a Bearer token:

Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx

End-user sessions (for actions signed by the cardholder's wallet) use Sign-In with Ethereum on top of the partner key. See Authentication.

Environments

Environment	Key prefix	Behavior
Live	w3c_live_	Real cards, mainnet vaults
Sandbox	w3c_test_	Test cards, testnet vaults, simulated authorizations

Errors

Errors use conventional HTTP status codes and a consistent body:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Vault balance does not cover the requested amount.",
    "requestId": "req_b81f2c"
  }
}

Status	Meaning
400	Invalid request body or parameters
401	Missing or invalid API key
403	Key valid but not allowed for this resource
404	Resource not found
409	Conflict with resource state (e.g. activating a voided card)
429	Rate limit exceeded
5xx	Platform error; safe to retry with backoff

Include the requestId when contacting support about a specific call.

Pagination

List endpoints return pages with an opaque cursor:

GET /transactions?limit=50&cursor=eyJvZmZzZXQiOjUwfQ

{ "data": [ … ], "nextCursor": "eyJvZmZzZXQiOjEwMH0" }

nextCursor is null on the last page.

Idempotency

Send an Idempotency-Key header on any POST you may retry. Two calls with the same key return the same result and create at most one resource.