Quickstart

Map your first WalletKit transaction intent

This guide walks through the core WalletKit workflow: authenticate, connect a sandbox provider profile, list wallets, and submit a policy-bound transaction intent.

Prerequisites

An Alloy API key — request sandbox access
A custody provider account for live integration planning, or the sandbox provider profile for docs testing
Node.js 18+ or Python 3.9+ (optional — you can use cURL directly)

Install the SDK

# No install needed — use cURL directly
export ALLOY_API_KEY="your-sandbox-key"

npm install @alloy-build/sdk

# Set your API key
export ALLOY_API_KEY="your-sandbox-key"

pip install alloy-sdk

# Set your API key
export ALLOY_API_KEY="your-sandbox-key"

Authenticate

Pass your API key as a Bearer token. The sandbox accepts test keys immediately.

curl -X GET https://sandbox.api.alloy.build/v1/health \
  -H "Authorization: Bearer $ALLOY_API_KEY"

# Response: {"status": "ok", "environment": "sandbox"}

import Alloy from '@alloy-build/sdk';

const alloy = new Alloy({
  apiKey: process.env.ALLOY_API_KEY,
  baseUrl: 'https://sandbox.api.alloy.build'
});

const health = await alloy.health.check();
console.log(health); // { status: 'ok', environment: 'sandbox' }

from alloy import AlloyClient
import os

client = AlloyClient(
    api_key=os.environ["ALLOY_API_KEY"],
    base_url="https://sandbox.api.alloy.build"
)

health = client.health.check()
print(health)  # {"status": "ok", "environment": "sandbox"}

Connect a provider

Connect your custody provider profile. In sandbox mode, use type: "sandbox" for a test profile with seeded wallets.

curl -X POST https://sandbox.api.alloy.build/v1/providers/connect \
  -H "Authorization: Bearer $ALLOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sandbox",
    "name": "My Sandbox Provider"
  }'

const provider = await alloy.providers.connect({
  type: 'sandbox',
  name: 'My Sandbox Provider'
});

console.log(provider.id); // "prov_sandbox_a1b2c3"

provider = client.providers.connect(
    type="sandbox",
    name="My Sandbox Provider"
)

print(provider.id)  # "prov_sandbox_a1b2c3"

List wallets

Fetch wallets across all connected providers through a single, normalized API.

curl -X GET https://sandbox.api.alloy.build/v1/wallets \
  -H "Authorization: Bearer $ALLOY_API_KEY"

# Response:
# {
#   "wallets": [
#     {
#       "id": "wal_sb_001",
#       "name": "USDC Operations",
#       "provider": "sandbox",
#       "assets": [{"symbol": "USDC", "balance": "50000.00"}]
#     }
#   ]
# }

const wallets = await alloy.wallets.list();

for (const wallet of wallets.data) {
  console.log(`${wallet.name} (${wallet.provider})`);
  for (const asset of wallet.assets) {
    console.log(`  ${asset.symbol}: ${asset.balance}`);
  }
}

wallets = client.wallets.list()

for wallet in wallets.data:
    print(f"{wallet.name} ({wallet.provider})")
    for asset in wallet.assets:
        print(f"  {asset.symbol}: {asset.balance}")

Submit a transaction intent

Transaction intents pass through policy and risk evaluation before reaching the provider. The response includes a deterministic status and policy receipt.

curl -X POST https://sandbox.api.alloy.build/v1/wallets/wal_sb_001/transaction-intents \
  -H "Authorization: Bearer $ALLOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDC",
    "amount": "1000.00",
    "destination": {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
    },
    "policy": "standard-transfer",
    "idempotency_key": "inv-2024-0847"
  }'

# Response:
# {
#   "id": "txn_int_a7f3e2",
#   "status": "approved",
#   "policy_receipt": "pk_eval_2024_a7f3",
#   "risk_score": 0.12,
#   "provider_tx_id": "fb_tx_9k2m"
# }

const intent = await alloy.wallets.createTransactionIntent(
  'wal_sb_001',
  {
    asset: 'USDC',
    amount: '1000.00',
    destination: {
      address: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18'
    },
    policy: 'standard-transfer',
    idempotencyKey: 'inv-2024-0847'
  }
);

console.log(intent.status);         // "approved"
console.log(intent.policyReceipt);  // "pk_eval_2024_a7f3"
console.log(intent.riskScore);      // 0.12

intent = client.wallets.create_transaction_intent(
    wallet_id="wal_sb_001",
    asset="USDC",
    amount="1000.00",
    destination={
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
    },
    policy="standard-transfer",
    idempotency_key="inv-2024-0847"
)

print(intent.status)          # "approved"
print(intent.policy_receipt)  # "pk_eval_2024_a7f3"
print(intent.risk_score)      # 0.12

Transaction intent state machine

Every transaction intent follows a deterministic state machine. Your integration only needs to handle these states.

created -> policy_check -> risk_check -> approved -> submitted -> confirmed

Branch: pending_human_approval

Branch: rejected (policy or risk)

Terminal: failed

Verify webhook signatures

Alloy signs webhook payloads with HMAC-SHA256. Always verify before processing.

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Map your first WalletKit transaction intent

Prerequisites

Install the SDK

Authenticate

Connect a provider

List wallets

Submit a transaction intent

Transaction intent state machine

Verify webhook signatures

Next steps

Explore all 8 modules

AI agent integration

Full API reference

Version matrix