Freeland

Agent-first API for wallet, cards, inbox OTP, Mr. Freeman, eSIM, VPN, and crypto invoices.

Freeland gives OpenClaw and other agents a real wallet, virtual cards, OTP inbox, Mr. Freeman chat, eSIM, VPN, and crypto invoice flows through one user-owned account.

Primary use cases:

• wallet, cards, and OTP-backed checkout flows
• connectivity services like eSIM and VPN
• platform-funded Mr. Freeman conversations
• invoice creation for collecting USDT

Authentication

All requests use the same Bearer token.

Authorization: Bearer $FREELAND_API_KEY

Production base URL:

BASE_URL="https://app.freeland.land/api.php"

Recommended helpers:

freeland_get() {
  local path="$1"
  curl --silent --show-error --get "$BASE_URL" \
    --data-urlencode "path=$path" \
    -H "Authorization: Bearer $FREELAND_API_KEY"
}

freeland_post() {
  local path="$1"
  local body="${2:-{}}"
  curl --silent --show-error -X POST "$BASE_URL?path=$path" \
    -H "Authorization: Bearer $FREELAND_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$body"
}

Trust Model

Freeland is designed for real, user-owned agent operations.

• The user owns the wallet, cards, inbox, connectivity services, and invoice flows.
• The API key grants access to the user's own account surface.
• Wallet balance and card balance are separate values.
• Provider readiness matters. If a service is offline, surface that honestly instead of pretending the flow worked.
• Sensitive outputs like PAN, CVV, billing address, inbox contents, and VPN configs should only be revealed when needed for the active task.

Autonomy Model

Freeland may be used in approval-based or pre-authorized mode.

• In approval-based mode, ask before issuing cards, topping up cards, withdrawing funds, buying eSIM plans, creating VPN subscriptions, or creating invoices.
• In pre-authorized mode, act only inside the user's stated balance, merchant, service, and spending boundaries.

Safety Boundaries

• Only use the user's own Freeland resources.
• Never invent billing data, cardholder details, mailbox codes, deposit addresses, or provider states.
• Do not retry balance-moving actions blindly. Read current state first.
• Treat provider failures, fraud checks, issuer declines, KYC gates, geography restrictions, and missing OTPs as hard boundaries.
• Do not expose sensitive card credentials or mailbox contents longer than necessary.
• For unfamiliar merchants, subscriptions, retries, and OTP-backed checkouts, read references/payment-safety.md first.
• For eSIM and VPN install or troubleshooting flows, read references/connectivity.md first.
• For payment collection and hosted payment links, read references/invoices.md first.

Default Behavior

• Start with GET /me.
• If the user asks for account readiness, report mailbox, wallet balance, deposit rail, card state, and service readiness separately.
• Treat wallet balance, card balance, and provider readiness as distinct facts.
• Use card.id for Freeland card routes.
• Lead with buyer-side wallet/card workflows. Use invoice creation only when the user explicitly wants to collect payments.
• For VPN, Freeland currently provides subscription plus WireGuard config delivery, not an in-browser tunnel.
• For eSIM, prefer install-ready profiles over re-listing the whole catalog when the user already owns one.

Core Jobs

1. Check account readiness

freeland_get "/me"
freeland_get "/wallet/balance"
freeland_get "/wallet/deposit-address"
freeland_get "/freeman/status"
freeland_get "/esim/status"
freeland_get "/vpn/status"

Important facts to surface:

• account status
• mailboxAddress
• wallet balance
• depositAddress status and address
• current card, if present
• Freeman, eSIM, and VPN readiness

2. Fund the wallet

freeland_get "/wallet/deposit-address"
freeland_get "/wallet/transactions?limit=20&offset=0"

Rules:

• deposits land on the user's USDT TRON rail
• wallet balance credits the net amount that actually reaches the address
• external sender, exchange, and network fees may reduce the credited amount before Freeland receives it

3. Issue and use a card

freeland_post "/cards/issue"
freeland_get "/cards/CARD_ID"
freeland_get "/cards/CARD_ID/balance"
freeland_get "/cards/CARD_ID/sensitive"
freeland_get "/cards/CARD_ID/transactions?limit=20&offset=0"

Rules:

• issue only when wallet balance is sufficient
• card routes use the Freeland card id
• use the sensitive response for PAN, CVV, expiry, cardholder name, and billing address
• after any merchant error, inspect card transactions before retrying

4. Top up a card

freeland_post "/cards/CARD_ID/topup" '{"amount":10,"currency":"USD"}'

Pre-flight:

1. read GET /wallet/balance
2. read GET /cards/CARD_ID
3. confirm the card is active
4. confirm the wallet covers the requested topup
5. only then send the topup request

5. Fetch OTP or receipt emails

freeland_get "/inbox/latest-otp"
freeland_get "/inbox?limit=20&offset=0"
freeland_get "/inbox/MESSAGE_ID"

Use this for 3DS, OTP verification, receipts, and merchant follow-up.

6. Talk to Mr. Freeman

freeland_get "/freeman/status"
freeland_post "/freeman/chat" '{"messages":[{"role":"user","content":"What am I avoiding?"}]}'

Mr. Freeman is platform-funded. Do not ask the user for a personal model key for this flow.

7. Work with eSIM

freeland_get "/esim/status"
freeland_get "/esim/plans?country=TR"
freeland_get "/esim/profiles"
freeland_post "/esim/purchase" '{"planId":"PLAN_ID"}'
freeland_get "/esim/profiles/PROFILE_ID"
freeland_post "/esim/profiles/PROFILE_ID/topup" '{"planId":"PLAN_ID"}'

Rules:

• only buy or top up when the provider is live
• after purchase, prefer install-ready fields like qrData, iosTapLink, and esimPassportUrl
• if a profile already exists, lead with install or topup instead of re-buying blindly

8. Work with VPN

freeland_get "/vpn/status"
freeland_get "/vpn/servers"
freeland_get "/vpn/subscription"
freeland_post "/vpn/subscription"
freeland_get "/vpn/config/SERVER_ID?protocol=wireguard"

Rules:

• VPN is subscription plus WireGuard config delivery
• after activation, help the user install or import the config into WireGuard
• do not describe this as an in-browser VPN tunnel

9. Create invoices

freeland_post "/invoices" '{"amount":25,"currency":"USD","description":"Freelance work","reference":"INV-001","expiresInMinutes":60}'
freeland_get "/invoices?limit=20&offset=0"

Use this when the user wants to collect USDT through Freeland.

Load References When Needed

• Read references/payment-safety.md before entering card details on an unfamiliar merchant, when a checkout keeps failing, or when OTP and retry boundaries matter.
• Read references/connectivity.md before helping with eSIM install, VPN import, mobile setup, or service troubleshooting.
• Read references/invoices.md when the user wants to create hosted invoices, explain invoice lifecycle, or reason about payment collection.

Good Default Prompt Shapes

• Check my Freeland account and tell me what is ready: wallet, card, inbox, Freeman, eSIM, and VPN.
• Use Freeland to issue a card and top it up if needed. Ask before any merchant checkout unless I say it is pre-authorized.
• Use Freeland inbox to fetch the latest OTP and confirm whether the last card payment actually went through.
• Use Freeland to buy an eSIM plan for Turkey and then guide me through installation.
• Use Freeland to activate VPN and hand me the right WireGuard config for my device.
• Use Freeland to create a USDT invoice for $25 and show me the payment link.

Scope Note

Freeland combines wallet, cards, inbox, character chat, connectivity services, and invoice collection. Lead with the simplest relevant workflow for the user's task instead of surfacing the whole platform at once.