API Reference

Base URL: https://execution.run/v1

Authentication

All endpoints require the X-API-Key header with your Card API key.

curl -H "X-API-Key: sk_live_your_card_key" https://execution.run/v1/balance

Get your card and wallet identity.

{ "cardId": "crd_xxx", "walletId": "exe_xxx", "address": "bot@exe_xxx" }

Get your wallet's current Shell balance.

{ "balance": 1000, "ceiling": 1000000 }

Get transaction history. Optional ?limit=N (default: 50, max: 100).

{ "transactions": [{ "id": "...", "type": "mint", "amount": 1000 }] }

Transfer Shells to another wallet or card address.

Request:

{ "to": "exe_xxx", "amount": 100, "purpose": "Payment" }

The to field accepts wallet IDs or card addresses (e.g., bot@exe_xxx).

Sign a challenge with your card's Ed25519 keypair.

Request:

{ "challenge": "base64_encoded_challenge" }

Response:

{ "signature": "base64_sig", "cardId": "crd_xxx", "walletId": "exe_xxx" }

Execute an LLM request.

Request:

{
  "request": {
    "model": "gemini-2.0-flash",
    "messages": [{ "role": "user", "content": "Hello!" }],
    "maxTokens": 100
  }
}

Response:

{ "content": "Hello!", "model": "gemini-2.0-flash", "cost": 4 }

These endpoints require no authentication.

Get a card's public key by address.

GET /identity/cardPublicKey?address=bot@exe_xxx

Verify a signature against a card's public key.

{ "address": "bot@exe_xxx", "challenge": "...", "signature": "..." }

Code	Status	Description
`INVALID_API_KEY`	401	Card API key is missing or invalid
`WALLET_FROZEN`	403	Wallet has been frozen
`INSUFFICIENT_BALANCE`	400	Not enough Shells
`WALLET_NOT_FOUND`	404	Wallet does not exist
`CARD_NOT_FOUND`	404	Card does not exist