What are Payment Keys?#

A Payment Key is a secret token linked to your NEAR account with a prepaid USD balance. It allows you to call OutLayer projects via HTTPS API without signing NEAR transactions.

Key Format#

Payment Keys are passed in the X-Payment-Key HTTP header:

X-Payment-Key: {owner}:{nonce}:{secret}

Example: X-Payment-Key: alice.near:0:K7xR2mN9pQs5vW3yZ8bF...

The secret is a 32-byte cryptographically random value encoded in Base64 (44 characters). It's generated client-side and shown only once during creation.

Creating Payment Keys#

Creating a Payment Key requires two transactions:

1. Create the key - Stores encrypted key data on-chain via store_secrets
2. Initial deposit - Transfers stablecoins via ft_transfer_call to fund the key

Via Dashboard#

1. Go to /payment-keys
2. Click "Create Payment Key"
3. Configure restrictions (see below)
4. Enter initial deposit amount (minimum $1)
5. Sign both transactions in your wallet
6. Copy the key immediately - it's shown only once!

Via CLI#

# Step 1: Generate random key (32 bytes in Base64)
SECRET_KEY=$(openssl rand -base64 32)
echo "Your secret key: $SECRET_KEY"

# Step 2: Create key on contract (initial_balance = 0)
near call outlayer.near store_secrets '{
  "accessor": {"System": "PaymentKey"},
  "profile": "0",
  "encrypted_data": "<encrypted JSON with key>"
}' --accountId alice.near --depositYocto 1

# Step 3: Top up with stablecoins
near call usdt.tether-token.near ft_transfer_call '{
  "receiver_id": "outlayer.near",
  "amount": "10000000",
  "msg": "{\"action\": \"top_up_payment_key\", \"nonce\": 0}"
}' --accountId alice.near --depositYocto 1

Key Restrictions#

Payment Keys can be restricted to limit their capabilities for security:

Project Restrictions#

// Key restricted to specific projects
{
  "key": "K7xR2mN9pQs5vW3yZ8bF...",
  "initial_balance": "10000000",
  "project_ids": ["alice.near/weather-api", "alice.near/ai-assistant"],
  "max_per_call": "1000000"
}

Spending Limits#

Balance Management#

Checking Balance#

View your key balance on the Payment Keys dashboard page. The balance shows:

• Initial balance - Total amount deposited
• Spent - Amount already used
• Available - Remaining balance (initial - spent)

Topping Up Balance#

Add more funds to an existing key:

1. Go to /payment-keys
2. Find your key and click "Top Up"
3. Enter amount (minimum $1)
4. Sign the ft_transfer_call transaction

# Top up via CLI (add $10 USDT to key with nonce 0)
near call usdt.tether-token.near ft_transfer_call '{
  "receiver_id": "outlayer.near",
  "amount": "10000000",
  "msg": "{\"action\": \"top_up_payment_key\", \"nonce\": 0}"
}' --accountId alice.near --depositYocto 1

Balance Protection#

OutLayer uses a reserved balance mechanism to prevent overdraft attacks:

1. When a call starts, the estimated cost is reserved
2. Call is rejected if available - reserved < estimated_cost
3. After completion, actual cost is charged and reservation is released

This prevents an attacker from spending $90 with a $1 balance by launching many parallel requests.

How Keys are Stored#

Payment Key data is stored as an encrypted secret on the OutLayer contract:

// Encrypted data structure (decrypted only in TEE)
{
  "key": "K7xR2mN9pQs5vW3yZ8bF...",      // 32-byte secret
  "initial_balance": "10000000",          // Total deposited (micro-units)
  "project_ids": ["alice.near/my-app"],   // Allowed projects ([] = any)
  "max_per_call": "1000000"               // Spending limit per call
}

Rate Limits#

To prevent abuse, Payment Keys have rate limits:

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1704067260

When limits are exceeded, you'll receive HTTP 429 Too Many Requests.

Security Best Practices#