Sardis , Payment OS for AI Agents

intent

Sardis gives AI agents non-custodial payment infrastructure: MPC wallets backed by Turnkey, natural language spending policies with automatic enforcement, stablecoin transfers across chains, virtual card issuance, and full audit trails. use this when an agent needs to execute a payment, create a wallet, check a balance, set spending limits, or issue a virtual card. do not use for general finance questions unrelated to agent payments.

inputs

environment variables:

• SARDIS_API_KEY (required): API key from https://app.sardis.sh or signup endpoint. treat as secret.
• SARDIS_API_URL (optional): override API endpoint. defaults to https://api.sardis.sh.

external connections:

• sardis payment api: https://api.sardis.sh. requires active network access and valid X-API-Key header on every request.
• turnkey (MPC provider): sardis wallets use Turnkey for key management. no separate setup needed; handled internally.
• stablecoin networks: base, ethereum, arbitrum, optimism, polygon, tempo. gas fees vary by chain.

binaries:

• curl: for making http requests to sardis api.
• jq (optional but recommended): for parsing json responses.

setup:

export SARDIS_API_KEY="sk_your_key_here"
export SARDIS_API_URL="https://api.sardis.sh"   # optional

get an api key at https://app.sardis.sh or programmatically:

curl -X POST https://api.sardis.sh/api/v2/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

procedure

step 1: create agent and wallet

call the create-agent endpoint to provision an agent identity with an auto-generated MPC wallet.

inputs: agent name (string), optional description (string).

command:

curl -X POST https://api.sardis.sh/api/v2/agents \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "description": "Payment agent for OpenAI billing"
  }'

output: agent object with agent_id (string), wallet_id (string), addresses (map of chain to address), kya_tier (string), created_at (timestamp).

example output:

{
  "agent_id": "agt_abc123",
  "name": "my-agent",
  "wallet_id": "wal_xyz789",
  "addresses": {"base": "0x...", "tempo": "0x..."},
  "kya_tier": "standard",
  "created_at": "2026-03-26T12:00:00Z"
}

step 2 (optional): attach additional wallet to agent

if you need a dedicated wallet for a specific chain, call the wallet-attachment endpoint.

inputs: agent_id (from step 1), chain (string: base, ethereum, arbitrum, optimism, polygon, or tempo), provider (string: always "turnkey" for mpc).

command:

curl -X POST https://api.sardis.sh/api/v2/agents/agt_abc123/wallet \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chain": "base", "provider": "turnkey"}'

output: wallet object with wallet_id, chain, address.

step 3: set spending policy

define spending rules in natural language. sardis parses them into enforceable constraints.

inputs: agent_id (from step 1), natural_language (string in plain english).

command:

curl -X POST https://api.sardis.sh/api/v2/policies/apply \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123",
    "natural_language": "Max $500 per day. Only allow OpenAI and Anthropic. No transactions over $200."
  }'

output: policy object with policy_id, parsed_rules (array of constraint objects), version (integer), applied_at (timestamp).

example output:

{
  "policy_id": "pol_def456",
  "agent_id": "agt_abc123",
  "parsed_rules": [
    {"type": "daily_limit", "value": "500.00", "currency": "USD"},
    {"type": "merchant_allowlist", "merchants": ["openai.com", "anthropic.com"]},
    {"type": "per_transaction_limit", "value": "200.00", "currency": "USD"}
  ],
  "version": 3,
  "applied_at": "2026-03-26T12:05:00Z"
}

step 4 (recommended): dry-run policy check before payment

pre-flight check whether a payment would be allowed by current policies. does not execute transaction.

inputs: agent_id, amount (string decimal), currency (string: USD, USDC, USDT, EURC, pathUSD), merchant (string, optional).

command:

curl -X POST https://api.sardis.sh/api/v2/policies/check \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123",
    "amount": "50.00",
    "currency": "USDC",
    "merchant": "aws.amazon.com"
  }'

output: policy_check object with allowed (boolean), reason (string), checks_passed (array of strings), checks_failed (array of strings), remaining_daily_limit (string decimal).

example output:

{
  "allowed": true,
  "reason": "All policy checks passed",
  "checks_passed": ["daily_limit", "per_tx_limit", "merchant_allowlist"],
  "checks_failed": [],
  "remaining_daily_limit": "450.00"
}

step 5: check wallet balance(s)

retrieve stablecoin balance on a single chain or across all chains.

single-chain balance: inputs: wallet_id, chain (string).

command:

curl -X GET "https://api.sardis.sh/api/v2/wallets/wal_xyz789/balance?chain=base" \
  -H "X-API-Key: $SARDIS_API_KEY"

output: balance object with wallet_id, chain, balance (string decimal), currency (string), updated_at (timestamp).

example output:

{
  "wallet_id": "wal_xyz789",
  "chain": "base",
  "balance": "1250.00",
  "currency": "USDC",
  "updated_at": "2026-03-26T12:00:00Z"
}

multi-chain balances: inputs: wallet_id.

command:

curl -X GET "https://api.sardis.sh/api/v2/wallets/wal_xyz789/balances" \
  -H "X-API-Key: $SARDIS_API_KEY"

output: array of balance objects, one per chain with active balance.

step 6: execute payment with automatic policy enforcement

unified payment endpoint. sardis automatically checks policy, routes to cheapest chain (if not specified), and returns tx hash on success.

inputs: to (string: merchant domain or address), amount (string decimal), currency (string: USDC, USDT, PYUSD, EURC, pathUSD), chain (string: base, ethereum, arbitrum, optimism, polygon, tempo; optional for auto-routing).

command:

curl -X POST https://api.sardis.sh/api/v2/pay \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "openai.com",
    "amount": "25.00",
    "currency": "USDC",
    "chain": "base"
  }'

output: payment object with status (string: completed, pending, failed), tx_hash (string), amount (string), currency (string), chain (string), policy_result (object with allowed boolean and checks_passed array), route (object with chain, provider, gas_estimate).

example output:

{
  "status": "completed",
  "tx_hash": "0xabc...def",
  "amount": "25.00",
  "currency": "USDC",
  "chain": "base",
  "policy_result": {"allowed": true, "checks_passed": ["daily_limit", "merchant_allowlist"]},
  "route": {"chain": "base", "provider": "alchemy", "gas_estimate": "0.0012"}
}

step 7: issue virtual card (optional)

issue a stablecoin-funded single-use or multi-use visa card for real-world purchases.

inputs: amount (string decimal), card_type (string: single_use or multi_use).

command:

curl -X POST https://api.sardis.sh/api/v2/cards/virtual/issue \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "card_type": "single_use"
  }'

output: card object with card_id, card_number (string), cvv (string), expiry (string: MM/YY), amount (string), currency (string: USD), card_type (string), status (string: active, inactive, expired).

example output:

{
  "card_id": "crd_abc123",
  "card_number": "4242424242424242",
  "cvv": "123",
  "expiry": "12/27",
  "amount": "25.00",
  "currency": "USD",
  "card_type": "single_use",
  "status": "active"
}

step 8: retrieve transaction status (optional)

query the status of a previously executed payment by tx hash.

inputs: tx_hash (string from step 6 output).

command:

curl -X GET "https://api.sardis.sh/api/v2/transactions/status/0xabc...def" \
  -H "X-API-Key: $SARDIS_API_KEY"

output: transaction object with tx_hash, status (string: confirmed, pending, failed), amount, currency, chain, block_number (integer, null if pending).

step 9: create spending mandate (optional)

define scoped, time-limited authority over funds. useful for delegating payment authority to sub-agents.

inputs: wallet_id, agent_id, max_amount (string decimal), currency (string), expires_at (timestamp), merchant_allowlist (optional array of strings).

command:

curl -X POST https://api.sardis.sh/api/v2/mandates \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "wal_xyz789",
    "agent_id": "agt_abc123",
    "max_amount": "1000.00",
    "currency": "USDC",
    "expires_at": "2026-04-01T00:00:00Z",
    "merchant_allowlist": ["openai.com", "anthropic.com"]
  }'

output: mandate object with mandate_id, wallet_id, agent_id, max_amount, currency, expires_at, merchant_allowlist, created_at.

decision points

if api key is missing or invalid: the api returns 401 unauthorized. check that SARDIS_API_KEY is set and correct. regenerate at https://app.sardis.sh if needed.

if payment is blocked by policy: the api returns 403 forbidden with error code POLICY_VIOLATION. the response includes the limit, current spend, and requested amount. do not retry with the same payload. either wait for the next period (e.g. daily reset), increase the limit via step 3, or add the merchant to the allowlist.

if wallet has insufficient balance: the api returns 400 bad request with error code INSUFFICIENT_BALANCE. fund the wallet before retrying. check step 5 to verify balance.

if chain is omitted from payment request: sardis auto-routes to the cheapest chain based on current gas prices and token liquidity. do not assume a specific chain; always parse the route object in the response to confirm where the transaction executed.

if natural language policy is ambiguous: the policy-preview endpoint (step 3 variant) returns the parsed rules for review before applying. inspect parsed_rules to ensure the constraints match intent. if rules are incorrect, revise the natural_language string and preview again.

if rate limit is hit (429 response): back off exponentially. sardis allows ~100 requests per minute per api key. implement retry logic with jitter (1s, 2s, 4s, 8s, 16s) before failing.

if network request times out: assume the request may have partially completed. poll the transaction status (step 8) by tx_hash before retrying. do not blindly re-execute payments without confirming prior status.

if recipient address format is invalid: the api returns 400 bad request. always validate address format (0x prefix, 40 hex chars for evm; valid domain name for merchant payment) before step 6.

if token is not supported on chosen chain: the api returns 400 bad request with list of supported tokens per chain. consult the supported chains and tokens table below and select a valid pairing.

if mandate has expired: sardis will reject payments under the mandate with a 403 forbidden. create a new mandate with a future expires_at timestamp to continue delegated spending.

output contract

successful payment execution (step 6):

• http status 201 created.
• response body contains payment object with status="completed", tx_hash matching on-chain transaction, amount echoed, currency echoed, chain used, policy_result.allowed=true, route with chain and gas_estimate.
• transaction visible on block explorer (etherscan, basescan, etc.) within 15-60 seconds depending on chain congestion.

successful balance check (step 5):

• http status 200 ok.
• response body contains balance object with wallet_id, chain, balance (string decimal, may be "0.00"), currency, updated_at (rfc3339 timestamp, refresh within 30 seconds).

successful policy application (step 3):

• http status 201 created.
• response body contains policy object with policy_id, parsed_rules array (each with type, value, currency, and optional merchant list), version (incremented), applied_at (timestamp).

successful policy check (step 4):

• http status 200 ok.
• response body contains check result with allowed (boolean), reason (string), checks_passed (array of constraint names), checks_failed (array of constraint names if denied), remaining_daily_limit (string).

successful agent creation (step 1):

• http status 201 created.
• response body contains agent object with agent_id, wallet_id, addresses (map of chain to address), kya_tier, created_at.

successful wallet attachment (step 2):

• http status 201 created.
• response body contains wallet object with wallet_id, chain, address.

successful virtual card issuance (step 7):

• http status 201 created.
• response body contains card object with card_id, card_number, cvv, expiry (MM/YY), amount, currency, card_type, status=active.

error responses:

• 400 bad request: invalid parameters (malformed amount, unsupported token, invalid address format). check error.code and error.details.
• 401 unauthorized: missing or invalid api key.
• 403 forbidden: policy violation (code POLICY_VIOLATION) or mandate expired. error.details includes limit, current, requested.
• 404 not found: wallet, agent, or transaction does not exist.
• 429 too many requests: rate limited. retry after exponential backoff.
• 500 internal server error: contact support@sardis.sh with tx_hash or request id from response headers.

outcome signal

user sees payment completed: response status is 201, status="completed", and tx_hash is present. transaction is visible on the appropriate block explorer within 1-2 blocks.

user sees balance updated: response status is 200, balance reflects most recent on-chain state (refreshed within 30 seconds), updated_at timestamp is recent.

user sees policy enforced: payment request to step 6 returns 403 forbidden with error code POLICY_VIOLATION before any funds move. no on-chain transaction is created.

user sees policy preview parsed correctly: step 3 preview response shows parsed_rules array with constraint types (daily_limit, per_transaction_limit, merchant_allowlist) and values matching the natural language input.

user sees virtual card ready to use: response status is 201, card_number and cvv are present, status="active", and expiry is in the future. card can be used immediately for real-world purchases.

user sees spending mandate delegated: response status is 201, mandate_id is present, merchant_allowlist and max_amount are applied. subsequent payments under this mandate are routed through the constraint checks.

---

supported chains and tokens

chain	tokens
base	usdc, eurc
ethereum	usdc, usdt, pyusd, eurc
arbitrum	usdc, usdt
optimism	usdc, usdt
polygon	usdc, usdt, eurc
tempo	pathusd

error codes reference

code	meaning	recovery
policy_violation	spending rule blocked transaction	adjust policy, wait for period reset, or increase limits
insufficient_balance	wallet has no funds	deposit stablecoins to wallet address
invalid_api_key	auth header missing or wrong	regenerate key at app.sardis.sh
invalid_address	recipient address malformed	validate evm address (0x...) or merchant domain
unsupported_token	token not available on chain	use supported pairing from table above
rate_limit_exceeded	too many requests per minute	back off exponentially and retry
network_timeout	request did not complete	poll transaction status; do not blindly retry
merchant_not_allowed	merchant blocked by policy	add to allowlist via policy step 3

complete onboarding flow (example)

# 1. Create agent (auto-provisions wallet)
AGENT=$(curl -s -X POST https://api.sardis.sh/api/v2/agents \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "billing-agent", "description": "Handles API billing"}')
AGENT_ID=$(echo $AGENT | jq -r '.agent_id')
WALLET_ID=$(echo $AGENT | jq -r '.wallet_id')
echo "Agent: $AGENT_ID, Wallet: $WALLET_ID"

# 2. Set spending policy
curl -s -X POST https://api.sardis.sh/api/v2/policies/apply \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\": \"$AGENT_ID\", \"natural_language\": \"Max \$100 per transaction, \$500 per day. Only OpenAI and Anthropic.\"}"

# 3. Check balance
curl -s -X GET "https://api.sardis.sh/api/v2/wallets/$WALLET_ID/balances" \
  -H "X-API-Key: $SARDIS_API_KEY" | jq '.'

# 4. Dry-run policy check
curl -s -X POST https://api.sardis.sh/api/v2/policies/check \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\": \"$AGENT_ID\", \"amount\": \"25.00\", \"currency\": \"USDC\", \"merchant\": \"openai.com\"}"

# 5. Execute payment (policy auto-enforced)
curl -s -X POST https://api.sardis.sh/api/v2/pay \
  -H "X-API-Key: $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "openai.com", "amount": "25.00", "currency": "USDC", "chain": "base"}'

related skills

• sardis-balance: read-only balance checking and analytics.
• sardis-policy: natural language spending policy management.
• sardis-cards: virtual card issuance and management.
• sardis-guardrails: circuit breaker and kill switch controls.
• sardis-identity: agent identity with tap verification.
• sardis-escrow: smart contract escrow for agent-to-agent payments.
• sardis-tempo-pay: mpp-native payments on tempo mainnet.

links

• website: https://sardis.sh
• dashboard: https://app.sardis.sh
• api docs: https://api.sardis.sh/api/v2/docs
• github: https://github.com/EfeDurmaz16/sardis
• support: support@sardis.sh

---