Agent Documentation

Everything your AI agent needs to be ready for the Agent Economy, from wallets and transfers to escrow and swaps.

Need full host + agent onboarding? Use the Openclaw setup tutorial.

Ready to Build AI-Powered Crypto Agents?

Create your account and start integrating the AgentWalletAPI into your AI applications.

Getting Started

Choose your preferred setup path: manual step-by-step or let your AI agent handle everything automatically.

🤖 Fully Automated Setup Path

Let your AI agent handle the entire setup process.

Create your account and generate an API key.

Give your AI agent this prompt

Simply click the button below to get started in minutes.

1Please install the OpenClawCash skill from the following repository:
2https://github.com/openclawcash/agentwalletapi
3
4Once installed, set it up and configure it for use. 
5Then list all available wallets  
6Confirm that you can successfully connect to them  
7Provide a clear list of everything we can do with openclawcash.com
8
9Here is the API key:
10[YOUR_API_KEY]

Or install with

Simply click the button and get started in minutes.

Manual Setup Path

Step-by-step setup where you control each action.

Create your account and first wallet through the dashboard.

Generate API key

Create an API key in settings and store it securely.

Share with your agent

Give your agent the API key and let it make the first API call.

Authentication: Include your API key on every request as X-Agent-Key: occ_your_api_key

API keys can be scoped to EVM-only or Solana-only and limited to testnet mode by disabling live transactions.

Essential API Calls

Start with listing wallets (above), then try these common operations. All examples use walletId from the list call.

List Wallets

1curl https://openclawcash.com/api/agent/wallets \
2  -H "X-Agent-Key: occ_your_api_key"

Transfer USDC

1curl -X POST https://openclawcash.com/api/agent/transfer \
2  -H "Content-Type: application/json" \
3  -H "X-Agent-Key: occ_your_api_key" \
4  -d '{
5    "walletId": "Q7X2K9P",
6    "to": "0xRecipientWalletAddress...",
7    "token": "USDC",
8    "amountDisplay": "100"
9  }'

Check Solana Balances

1curl -X POST https://openclawcash.com/api/agent/token-balance \
2  -H "Content-Type: application/json" \
3  -H "X-Agent-Key: occ_your_api_key" \
4  -d '{
5    "walletId": "YUZE66Z",
6    "chain": "solana"
7  }'

Quick Workflows

Choose the workflow first, then drill into endpoint details.

Read Wallet State

Inventory wallets, inspect balances, and monitor activity before actions.

Wallets Wallet Detail Token Balance

Guide: How to give any AI agent a safe crypto wallet

Move Funds

Send crypto securely with spending guards, then track every move in transaction history.

Transfer Transactions

Guide: Why spending limits change the equation

Account Setup

Set up your agent handle to send or receive payments from any other agent on the platform.

Set User Tag Get User Tag

Guide: Agent discovery - pay anyone by their handle

Agent-to-Agent Commerce

Create checkout requests, manage escrow, and handle buyer/seller flows.

Create Pay Request Get Escrow Release

Case study: $10K agent escrow deal on mainnet

Trade on DEX

Get the best prices across Uniswap & Jupiter, approve tokens, and execute swaps seamlessly.

Quote Approve Swap

Tutorial: Build an autonomous trading agent

Trade on Polymarket

Verify venue account, place/redeem positions, then monitor open orders and positions.

Account Market Order Redeem Positions

Case study: +7,735 USDC in 7 days

Wallet Operations

15 endpoints

Public Token List (no auth)

Public

GET

/api/public/tokenlist

Wallet Operations

Standards-compliant Token Lists v1 document covering every chain OpenClawCash supports. No auth required, CORS-allowed, cacheable.

Default (extended=true): curated set merged with the Uniswap default list (EVM) and the Jupiter verified list (Solana). Curated entries win on (chainId, address) dedupe.
?extended=false: curated only. Zero external dependencies, smaller payload, longer cache.
?chainId=<num>: scope to one chain: 1 Mainnet, 137 Polygon, 8453 Base, 11155111 Sepolia, 101 Solana mainnet.

HTTP Request

GET /api/public/tokenlist

Request Parameters / Body

1// No request body or auth header needed (public GET).
2// Optional query params:
3//   ?extended=true|false   // default true; false = curated only
4//   ?chainId=<num>          // scope to one chain (e.g. 8453 for Base)
5// Examples:
6//   /api/public/tokenlist
7//   /api/public/tokenlist?chainId=8453
8//   /api/public/tokenlist?extended=false

Request Example

1# All chains, extended (default)
2curl https://your-app.vercel.app/api/public/tokenlist
3
4# Just Base
5curl "https://your-app.vercel.app/api/public/tokenlist?chainId=8453"
6
7# Curated only (no Uniswap/Jupiter)
8curl "https://your-app.vercel.app/api/public/tokenlist?extended=false"

Response Example

1{
2  "name": "OpenClawCash Tokens (extended via Uniswap + Jupiter)",
3  "timestamp": "2026-05-03T12:00:00.000Z",
4  "version": { "major": 1, "minor": 0, "patch": 0 },
5  "keywords": ["openclawcash", "managed-wallets", "agent-wallet", "extended", "uniswap", "jupiter"],
6  "tokens": [
7    {
8      "chainId": 1,
9      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
10      "name": "USD Coin",
11      "symbol": "USDC",
12      "decimals": 6,
13      "logoURI": "https://assets.coingecko.com/coins/images/6319/standard/usdc.png"
14    },
15    {
16      "chainId": 8453,
17      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
18      "name": "USD Coin",
19      "symbol": "USDC",
20      "decimals": 6,
21      "logoURI": "https://assets.coingecko.com/coins/images/6319/standard/usdc.png"
22    },
23    {
24      "chainId": 101,
25      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
26      "name": "USD Coin",
27      "symbol": "USDC",
28      "decimals": 6,
29      "logoURI": "https://assets.coingecko.com/coins/images/6319/standard/usdc.png"
30    }
31  ]
32}

List Wallets

Auth Required

GET

/api/agent/wallets

Wallet Operations

List all wallets accessible to your API key. Returns the walletId values to use in API calls, plus labels, addresses, networks, and chain.

Default response is discovery-only (no balances).
Add ?includeBalances=true to include native balance and nativeSymbol per wallet.

Get Wallet Detail + Balances

Auth Required

GET

/api/agent/wallet

Wallet Operations

Fetch one wallet by walletId, walletLabel, or walletAddress and return wallet fields plus native balance and token balances. For API calls, prefer the walletId returned by List Wallets.

Rename Wallet

Auth Required

PATCH

/api/agent/wallet

Wallet Operations

Update a wallet's label. Metadata only: no funds move and no special API key permission is required.

Selecting the wallet: by walletId, walletLabel (its current label), or walletAddress.
Label rules: 1-32 characters (letters, numbers, spaces, . _ - ( ) #, starting with a letter or number). Must not match another wallet's label or a wallet ID.
Rate limit: its own per-key limit, separate from create/import (429 with Retry-After).
Duplicate labels: older accounts may have wallets that share a label. Selecting one of those by walletLabel returns 409 wallet_label_ambiguous with the matching walletIds, and this endpoint is how to give one of them a unique label.

Wallet Transaction History

Auth Required

GET

/api/agent/transactions

Wallet Operations

List merged per-wallet transaction history (on-chain + app-recorded). Works for EVM and Solana wallets.

Selecting the wallet: pass walletId, walletLabel, or walletAddress as a query parameter.
chain (optional): enforces wallet-chain match.
network (optional): lets EVM wallets scope to a single EVM chain (mainnet, polygon-mainnet, base-mainnet, sepolia) or merge across the bucket with network=all. Each row carries data.network so you always know which chain it ran on.
Fees: fee is the network (gas) fee in native base units ("0" until the transaction is indexed on-chain). platformFee is the OpenClawCash platform fee in base units of the transferred token, and feePercent is its rate.

Get Policies

Auth Required

GET

/api/agent/policies

Wallet Operations

List policies across all wallets accessible to your API key. Returns hydrated policy data including current usage for spending limit policies (daily, weekly, monthly).

Get Policy

Auth Required

GET

/api/agent/policy

Wallet Operations

Get policies for a specific wallet by walletId, walletLabel, or walletAddress. Returns hydrated policy data including current usage for spending limit policies.

Transfer Native or Tokens

Auth Required

POST

/api/agent/transfer

Wallet Operations

Send native coin or token from a managed wallet. EVM wallets support ETH/ERC-20, Solana wallets support SOL/SPL.

Source wallet: walletId, walletLabel, or walletAddress.
Token: by symbol or address/mint.
Amount: amountDisplay (human units) or valueBaseUnits (base units). Legacy aliases amount / value are accepted for compatibility.
chain (optional): enforces wallet-chain match.
network (optional): lets EVM wallets transact on a non-default EVM chain (e.g. network: "base-mainnet" to send Base USDC from a polygon-home wallet). Omit to use the wallet's default.
memo (optional, Solana only): max 5 words, max 256 UTF-8 bytes.
Minimum amount: native transfers (EVM + Solana) run a preflight for the minimum transferable amount that accounts for transaction fees, network fees, and chain constraints.

Token Balance

Auth Required

POST

/api/agent/token-balance

Wallet Operations

Check balances for all supported tokens on a wallet, or filter by token symbol/address. Select the wallet with walletId or walletAddress. Works for EVM (ETH/ERC-20) and Solana (SOL/SPL). Optional chain enforces wallet-chain match.

Supported Tokens

Auth Required

GET

/api/agent/supported-tokens

Wallet Operations

Returns recommended common, well-known tokens for a network. Requires X-Agent-Key.

Optional walletId, walletLabel, or walletAddress can be passed as query params to attach the request to wallet activity history.
You can still use any valid ERC-20 token (EVM) or any valid SPL mint (Solana) in wallet transfer/swap/balance endpoints.

Get Global User Tag

Auth Required

GET

/api/agent/user-tag

Wallet Operations

Read the account-level User Tag used by checkout flows. If the tag is not configured yet, this returns userTag: null.

Set Global User Tag (One-Time)

Auth Required

PUT

/api/agent/user-tag

Wallet Operations

Set your account-level User Tag once. Use 3-8 lowercase characters (a-z, 0-9, ., _, -). This tag is reused in checkout flows and cannot be changed after it is set.

Token Approval

Auth Required

POST

/api/agent/approve

Wallet Operations

Approve a spender contract to use ERC-20 tokens from the wallet (EVM only).

Source wallet: walletId or walletAddress.
chain: "evm" (optional).
network (optional): lets EVM wallets approve on a non-default EVM chain (mainnet, polygon-mainnet, base-mainnet, sepolia). Omit to use the wallet's default.

Create Wallet (Agent API)

Auth Required

Requires wallet creation permission

POST

/api/agent/wallets/create

Wallet Operations

Create a new API-key-managed wallet. This endpoint requires wallet creation permission and a passphrase-safe flow: save the export passphrase first, then send it with explicit confirmation.

Import Wallet (Agent API)

Auth Required

Requires wallet import permission

POST

/api/agent/wallets/import

Wallet Operations

Import an existing wallet under agent API auth. Requires wallet import permission on the API key. Supported networks: mainnet, polygon-mainnet, and solana-mainnet.

Checkout & Escrow (Agent-to-Agent)

17 endpoints

Create Checkout Pay Request

Auth Required

POST

/api/agent/checkout/payreq

Checkout & Escrow (Agent-to-Agent)

Create a signed pay request and dedicated escrow wallet using the account's global User Tag. Requires Idempotency-Key header. Term fields: expiresInSeconds = funding deadline; autoReleaseSeconds = when funded escrow can auto-release if no dispute; disputeWindowSeconds = how long buyer can open dispute after auto-release point. Each must be at least 3600 seconds, and disputeWindowSeconds must be less than or equal to autoReleaseSeconds.

HTTP Request

POST /api/agent/checkout/payreq

Request Parameters / Body

1{
2  "walletId": "Q7X2K9P",
3  "amount": "1000000",
4  "expiresInSeconds": 3600,
5  "autoReleaseSeconds": 3600,
6  "disputeWindowSeconds": 3600,
7  "metadata": { "orderRef": "INV-4821" }
8}

Request Example

1curl -X POST https://your-app.vercel.app/api/agent/checkout/payreq \
2  -H "Content-Type: application/json" \
3  -H "X-Agent-Key: occ_your_api_key" \
4  -H "Idempotency-Key: checkout-create-001" \
5  -d '{
6    "walletId": "Q7X2K9P",
7    "amount": "1000000"
8  }'

Response Example

1{
2  "id": "pr_a1b2c3",
3  "escrowId": "es_d4e5f6",
4  "state": "pending_funding",
5  "chain": "evm",
6  "network": "polygon-mainnet",
7  "assetSymbol": "USDC",
8  "amount": "1000000",
9  "sellerTag": "your-global-user-tag",
10  "payreqToken": "<base64url>",
11  "escrowAddress": "0xEscrowWallet...",
12  "expiresAt": "2026-03-07T12:00:00.000Z",
13  "autoReleaseAt": "2026-03-07T13:00:00.000Z",
14  "disputeWindowSeconds": 3600
15}

Get Checkout Pay Request

Auth Required

GET

/api/agent/checkout/payreq/:id

Checkout & Escrow (Agent-to-Agent)

Fetch pay request details by pay request id.

Confirm Escrow Funding

Auth Required

POST

/api/agent/checkout/escrows/:id/funding-confirm

Checkout & Escrow (Agent-to-Agent)

Confirm on-chain escrow funding with transaction hash and confirmation depth. This endpoint does not assign buyer identity. Agent calls are limited to seller or already-assigned buyer. Requires Idempotency-Key.

Get Escrow

Auth Required

GET

/api/agent/checkout/escrows/:id

Checkout & Escrow (Agent-to-Agent)

Read escrow lifecycle status, funding tx, release/refund tx, and proof/dispute fields.

Accept Escrow As Buyer

Auth Required

POST

/api/agent/checkout/escrows/:id/accept

Checkout & Escrow (Agent-to-Agent)

Claim/approve an escrow as buyer before funding. Requires Idempotency-Key.

Submit Escrow Proof

Auth Required

POST

/api/agent/checkout/escrows/:id/proof

Checkout & Escrow (Agent-to-Agent)

Seller submits proof metadata before auto-release deadline. Requires Idempotency-Key.

Open Escrow Dispute

Auth Required

POST

/api/agent/checkout/escrows/:id/dispute

Checkout & Escrow (Agent-to-Agent)

Assigned buyer opens a dispute before dispute deadline. External buyers without an account must claim buyer access first. Requires Idempotency-Key.

Quick Pay Escrow (Direct)

Auth Required

POST

/api/agent/checkout/escrows/:id/quick-pay

Checkout & Escrow (Agent-to-Agent)

Directly fund escrow from the selected buyer wallet when settlement token balance is sufficient. Requires Idempotency-Key.

Swap And Pay Escrow

Auth Required

POST

/api/agent/checkout/escrows/:id/swap-and-pay

Checkout & Escrow (Agent-to-Agent)

Two-phase flow for buyer wallet: quote with confirm:false, then execute with confirm:true. Requires Idempotency-Key.

Cancel Escrow

Auth Required

POST

/api/agent/checkout/escrows/:id/cancel

Checkout & Escrow (Agent-to-Agent)

Cancel an escrow while it is still cancellable in lifecycle. Requires Idempotency-Key.

Release Escrow

Auth Required

POST

/api/agent/checkout/escrows/:id/release

Checkout & Escrow (Agent-to-Agent)

Buyer-only action: release escrow to seller payout wallet, deducting gas from escrow amount. External buyers can use the public wallet-sign release flow. Requires Idempotency-Key.

Refund Escrow

Auth Required

POST

/api/agent/checkout/escrows/:id/refund

Checkout & Escrow (Agent-to-Agent)

Seller-only action: refund escrow to buyer funding address, deducting gas from escrow amount. Requires Idempotency-Key.

Public Hosted Checkout Pay Request Read

Public

GET

/api/checkout/payreq/:id

Checkout & Escrow (Agent-to-Agent)

Public endpoint used by hosted checkout links to fetch pay request + escrow metadata by id.

External Buyer Auth Challenge

Public

POST

/api/checkout/public/escrows/:id/buyer-auth/challenge

Checkout & Escrow (Agent-to-Agent)

Public endpoint: issue a short-lived wallet-sign challenge for the escrow funding buyer address.

External Buyer Auth Verify

Public

POST

/api/checkout/public/escrows/:id/buyer-auth/verify

Checkout & Escrow (Agent-to-Agent)

Public endpoint: verify wallet signature and receive short-lived escrow-scoped buyer token.

External Buyer Proof View

Public

GET

/api/checkout/public/escrows/:id/proof

Checkout & Escrow (Agent-to-Agent)

Read seller proof for an escrow using external buyer token (Authorization: Bearer <token>).

External Buyer Release

Public

POST

/api/checkout/public/escrows/:id/release

Checkout & Escrow (Agent-to-Agent)

Release escrow using external buyer token (Authorization: Bearer <token>). Dispute remains account-claim flow.

Webhooks

4 endpoints

Wallet webhooks

Wallet webhooks watch your wallets, not a checkout, so they fire for every payment your agents make. They are their own product in the dashboard, with their own page: Wallet webhooks.

Event types

Wallet webhooks watch your wallets rather than a checkout, so they cover everything that moves on them, including every payment your agents make through the API.

wallet.transaction.confirmed: a transaction was recorded on one of your wallets.

A transfer that fails is refused before it is recorded, so there is no failed wallet event: these events report what landed.

One transfer writes a row for each of your own wallets it touches, so an account paying from one of its wallets into another receives two confirmed events for it: one with direction outgoing, one with direction incoming, both carrying the same hash. A transfer to an address you do not hold produces a single event.

Wallet events are never sent to a * subscription, so list them by name when you create an endpoint.

Example body: wallet.transaction.confirmed

1{
2  "eventId": "evt_...",
3  "eventType": "wallet.transaction.confirmed",
4  "createdAt": "...",
5  "data": {
6    "walletId": "Q7X2K9P",
7    "walletAddress": "0x...",
8    "network": "sepolia",
9    "transactionId": 7,
10    "type": "transfer",
11    "status": "confirmed",
12    "direction": "outgoing",
13    "hash": "0x...",
14    "from": "0x...",
15    "to": "0x...",
16    "value": "1000000000000000",
17    "fee": "0",
18    "platformFee": "0"
19  }
20}

Set Up Webhooks With Your Agent

Paste this prompt into your agent. It walks your user through creating a signed webhook and verifying every delivery. Endpoint reference: Create Webhook.

webhook-setup-promptAgent-ready

You are setting up an OpenClawCash webhook for your user, so their own server is notified whenever a transaction happens on one of their wallets.

Docs: https://openclawcash.com/docs#post-api-agent-checkout-webhooks
API base: https://openclawcash.com
Auth header on every call: X-Agent-Key: <your OpenClawCash API key>

Step 1. Ask your user for two things:
- The https URL on their server that will receive events. It must be reachable from the internet. Plain http, private addresses and redirects are refused.
- Which events they want. Wallet events: wallet.transaction.confirmed (listed by name). Checkout events: escrow.funded, escrow.released, escrow.refunded, escrow.failed and the other escrow.* types. If they are unsure, suggest wallet.transaction.confirmed.

Step 2. Create the webhook:
POST /api/agent/checkout/webhooks
Headers: X-Agent-Key, Content-Type: application/json, Idempotency-Key: <a new unique value>
Body: {"url":"<their url>","eventTypes":["wallet.transaction.confirmed"],"enabled":true}
The response has publicId and a one-time secret that starts with whsec_.

Step 3. Give the secret to your user right away and tell them to store it as a secret on their server (for example the environment variable OCC_WEBHOOK_SECRET). It is shown only once. Do not post it in shared channels and do not keep it in your own memory or logs. If it is lost, delete the webhook (DELETE /api/agent/checkout/webhooks/:id with an Idempotency-Key) and create a new one.

Step 4. Give your user this receiver code (Node) and explain the rules: read the raw request body before any JSON parsing, verify the signature, reject timestamps older than 5 minutes, answer with a 2xx within 10 seconds, and de-duplicate on the webhook-id header because a delivery can arrive more than once.

import crypto from "node:crypto";

function verifyWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = Number(headers["webhook-timestamp"]);
  if (!id || !Number.isInteger(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(id + "." + timestamp + "." + rawBody).digest("base64");
  return String(headers["webhook-signature"] || "").split(" ").some((entry) => {
    const given = Buffer.from(entry.split(",")[1] || "");
    const want = Buffer.from(expected);
    return given.length === want.length && crypto.timingSafeEqual(given, want);
  });
}

Step 5. Explain what will arrive: a JSON POST with { eventId, eventType, createdAt, data }. For wallet events, data has walletId, walletAddress, network, transactionId, type, status, direction, hash, from, to, value, fee and platformFee (value and fees are strings in base units; direction is incoming or outgoing; from is the sending address when it is known). A delivery that does not get a 2xx is retried for about a day. A 410 response switches the endpoint off.

Step 6. Check the setup. GET /api/agent/checkout/webhooks should list the webhook with enabled: true. Then ask your user to open https://openclawcash.com/webhooks, find the endpoint and press Test, or make a small transfer on a test network such as Sepolia, and confirm the delivery reaches their server.

Step 7. Report back with the publicId, the subscribed event types, and confirmation that your user has stored the secret. Never print the secret again.

Delivery, signing and retries

Each delivery is a JSON POST signed per the Standard Webhooks scheme.

Event types

escrow.*: checkout (escrow) events, for example escrow.funded, escrow.released and escrow.refunded.
*: accepted on create and update, and covers escrow events only.

Wallet events are their own group and must be named.

Request headers

Header	Value
`webhook-id`	The event id (`eventId` in the body). De-duplicate on it.
`webhook-timestamp`	Unix seconds.
`webhook-signature`	`v1,<base64 HMAC-SHA256 of "{id}.{timestamp}.{body}">`. The header can list several signatures separated by spaces.
`x-occ-signature`	Older signature header, still sent.

Verify every delivery

Read the raw request body before any JSON parsing.
Reject the delivery if webhook-timestamp is more than 5 minutes old.
Compute the HMAC-SHA256 of {id}.{timestamp}.{body}, base64-encode it, and compare it in constant time to each v1, entry in webhook-signature. The key is the base64-decoded part of the secret after whsec_.
De-duplicate on webhook-id: a delivery can arrive more than once.
Answer with a 2xx within 10 seconds.

A complete Node verifier is in the Node.js tab of Create Webhook.

Secret and retries

The signing secret (whsec_...) is returned once, when you create the webhook. Store it on your server. If it is lost, delete the webhook and create a new one.
Failed deliveries (a non-2xx answer, or no answer within 10 seconds) are retried with growing delays for about a day. A retry leaves as soon as a delivery pass runs: publishing a new event starts one straight away, and the service also runs passes on a schedule.
A 410 response disables the endpoint instead of retrying, and closes the deliveries already queued for it.

Create Webhook

Auth Required

POST

/api/agent/checkout/webhooks

Webhooks

Subscribe to events at a URL you control. Returns the webhook publicId and a one-time secret (shown once, store it).

Event types: escrow.* checkout events, plus wallet.transaction.confirmed by name. Wallet events are sent when a transaction is recorded on one of your wallets. * covers escrow events only.
Deliveries: signed JSON POSTs. See Delivery, signing and retries for headers, verification and retry behavior.
Requires Idempotency-Key.

HTTP Request

POST /api/agent/checkout/webhooks

Request Parameters / Body

1{
2  "url": "https://example.com/occ-webhook",
3  "eventTypes": ["escrow.released", "wallet.transaction.confirmed"],
4  "enabled": true
5}

Request Example

1curl -X POST https://your-app.vercel.app/api/agent/checkout/webhooks \
2  -H "Content-Type: application/json" \
3  -H "X-Agent-Key: occ_your_api_key" \
4  -H "Idempotency-Key: webhook-create-001" \
5  -d '{
6    "url": "https://example.com/occ-webhook",
7    "eventTypes": ["escrow.released", "wallet.transaction.confirmed"]
8  }'

Response Example

1{
2  "publicId": "wh_a1b2c3d4e5f6",
3  "url": "https://example.com/occ-webhook",
4  "enabled": true,
5  "eventTypes": ["escrow.released", "wallet.transaction.confirmed"],
6  "secret": "whsec_..."
7}

List Webhooks

Auth Required

GET

/api/agent/checkout/webhooks

Webhooks

List all webhook subscriptions registered for the API key owner. Returns each webhook's publicId, target URL, enabled flag, and subscribed eventTypes.

The signing secret is only returned at creation time and is never exposed by this endpoint.

Update Webhook

Auth Required

PATCH

/api/agent/checkout/webhooks/:id

Webhooks

Update the URL, event types, or enabled flag of an existing webhook subscription.

Provide at least one of url, eventTypes, or enabled.
Requires Idempotency-Key.

Delete Webhook

Auth Required

DELETE

/api/agent/checkout/webhooks/:id

Webhooks

Permanently remove a webhook subscription. Returns 204 No Content on success. Requires Idempotency-Key.

DEX Trading

2 endpoints

Token Swap (DEX)

Auth Required

POST

/api/agent/swap

DEX Trading

Execute a DEX swap using the wallet chain router: Uniswap v2 (or compatible) for EVM and Jupiter for Solana. Uses wallet-owned funds, applies the platform fee, and returns swap transaction metadata.

Source wallet: walletId or walletAddress.
chain (optional): enforces wallet-chain match.
network (optional): lets EVM wallets swap on a non-default EVM chain (mainnet, polygon-mainnet, base-mainnet, sepolia). Omit to use the wallet's default.

HTTP Request

POST /api/agent/swap

Request Parameters / Body

1{
2  "chain": "solana",
3  "walletId": "YUZE66Z",
4  "tokenIn": "SOL",
5  "tokenOut": "USDC",
6  "amountIn": "10000000",
7  "slippage": 0.5
8}

Request Example

1curl -X POST https://your-app.vercel.app/api/agent/swap \
2  -H "Content-Type: application/json" \
3  -H "X-Agent-Key: occ_your_api_key" \
4  -d '{
5    "chain": "solana",
6    "walletId": "YUZE66Z",
7    "tokenIn": "SOL",
8    "tokenOut": "USDC",
9    "amountIn": "10000000",
10    "slippage": 0.5
11  }'

Response Example

1{
2  "txHash": "5q6...abc",
3  "status": "confirmed",
4  "dex": "jupiter",
5  "amountOut": "123456",
6  "amountOutMin": "122839",
7  "tokenIn": "SOL",
8  "tokenOut": "USDC",
9  "fee": "100000",
10  "feePercent": "1%"
11}

Get Swap Quote

Auth Required

POST

/api/agent/quote

DEX Trading

Get a swap quote without executing a transaction. Requires X-Agent-Key.

Networks: Uniswap v2 (or compatible) on EVM (mainnet, polygon-mainnet, base-mainnet, sepolia) and Jupiter on Solana (solana-mainnet).
Wallet context (optional): walletId, walletLabel, or walletAddress attaches the quote to wallet activity history and validates chain context.

Cross-Chain Bridge

3 endpoints

Bridge Quote

Auth Required

POST

/api/agent/bridge/quote

Cross-Chain Bridge

Quote a cross-chain transfer routed through LiFi. The aggregator picks the underlying bridge (Across, Stargate, etc.) and announces it as bridgeName.

Required: fromNetwork, fromToken, toNetwork, toToken, and amountIn (base units integer string).
Support: EVM-EVM is fully supported. EVM<->Solana quoting works, but Solana source-side execute is gated to a follow-up.
Quote TTL: ~60s.

HTTP Request

POST /api/agent/bridge/quote

Request Parameters / Body

1{
2  "walletId": "Q7X2K9P",
3  "fromNetwork": "base-mainnet",
4  "fromToken": "USDC",
5  "toNetwork": "polygon-mainnet",
6  "toToken": "USDC",
7  "amountIn": "1000000",
8  "slippagePercent": 0.5
9}

Request Example

1curl -X POST https://your-app.vercel.app/api/agent/bridge/quote \
2  -H "Content-Type: application/json" \
3  -H "X-Agent-Key: occ_your_api_key" \
4  -d '{
5    "walletId": "Q7X2K9P",
6    "fromNetwork": "base-mainnet",
7    "fromToken": "USDC",
8    "toNetwork": "polygon-mainnet",
9    "toToken": "USDC",
10    "amountIn": "1000000"
11  }'

Response Example

1{
2  "quoteId": "quote_abc123",
3  "provider": "lifi",
4  "bridgeName": "across",
5  "fromNetwork": "base-mainnet",
6  "toNetwork": "polygon-mainnet",
7  "amountIn": "1000000",
8  "netAmountIn": "990000",
9  "amountOut": "988500",
10  "amountOutMin": "983557",
11  "providerFeeBaseUnits": "1500",
12  "providerFeeToken": "USDC",
13  "fee": "10000",
14  "feePercent": "1%",
15  "feeWaived": false,
16  "feeWalletAddress": "0xFee...",
17  "estimatedDurationSeconds": 60,
18  "expiresAt": "2026-05-05T17:30:00.000Z"
19}

Bridge Execute

Auth Required

POST

/api/agent/bridge/execute

Cross-Chain Bridge

Execute a previously quoted cross-chain bridge. The server signs the source-side transaction with the wallet's key, submits it to chain, and collects the platform fee.

Send the Idempotency-Key header for safe retries.
Returns sourceTxHash and bridgeTxId. Use /api/agent/bridge/status to track destination delivery.

Bridge Status

Auth Required

GET

/api/agent/bridge/status

Cross-Chain Bridge

Look up the status of a bridge transaction by bridgeTxId.

States: submitted, source_confirmed, destination_confirmed, completed, failed.
Returns the source and destination tx hashes once each side confirms, plus amountReceived once the bridge completes.

Polymarket

12 endpoints

Place Polymarket Limit Order

Auth Required

POST

/api/agent/venues/polymarket/orders/limit

Polymarket

Place a Polymarket limit order for a configured polygon-mainnet wallet. Setup is user-managed in dashboard at /venues/polymarket.

HTTP Request

POST /api/agent/venues/polymarket/orders/limit

Request Parameters / Body

1{
2  "walletId": "Q7X2K9P",
3  "tokenId": "1234567890",
4  "side": "BUY",
5  "price": 0.62,
6  "size": 25
7}

Request Example

1curl -X POST https://your-app.vercel.app/api/agent/venues/polymarket/orders/limit \
2  -H "Content-Type: application/json" \
3  -H "X-Agent-Key: occ_your_api_key" \
4  -d '{
5    "walletId": "Q7X2K9P",
6    "tokenId": "1234567890",
7    "side": "BUY",
8    "price": 0.62,
9    "size": 25
10  }'

Response Example

1{
2  "venue": "polymarket",
3  "status": "submitted",
4  "orderId": "optional-order-id",
5  "txHash": "optional-tx-hash"
6}

Place Polymarket Market Order

Auth Required

POST

/api/agent/venues/polymarket/orders/market

Polymarket

Place a Polymarket market order for a configured polygon-mainnet wallet.

Closing a position on an open market: default to side: SELL (SELL amount is shares). Use limit SELL only when a target price is explicitly requested.
Setup is user-managed in the dashboard at /venues/polymarket.

Polymarket Account Summary

Auth Required

GET

/api/agent/venues/polymarket/account

Polymarket

Read Polymarket account summary for a configured polygon-mainnet wallet.

Polymarket Market Resolver

Auth Required

GET

/api/agent/venues/polymarket/market/resolve

Polymarket

Resolve Polymarket marketUrl or slug and human-readable outcome to the exact CLOB tokenId for order placement.

Polymarket Market Search

Auth Required

GET

/api/agent/venues/polymarket/market/search

Polymarket

Search Polymarket markets by free-text query. Returns up to limit matching markets with their slugs, condition ids, outcomes, and active/closed flags.

Use this when you have a natural-language question and need candidate markets to narrow down with /market/resolve.

Polymarket Open Orders

Auth Required

GET

/api/agent/venues/polymarket/orders

Polymarket

List open Polymarket orders for a configured polygon-mainnet wallet.

Cancel Polymarket Order

Auth Required

POST

/api/agent/venues/polymarket/orders/cancel

Polymarket

Cancel a Polymarket order by orderId for a configured polygon-mainnet wallet.

Clear Polymarket Integration

Auth Required

POST

/api/agent/venues/polymarket/unlink

Polymarket

Clear stored Polymarket venue config for a configured polygon-mainnet wallet. This removes integration credentials/config only.

Polymarket Activity

Auth Required

GET

/api/agent/venues/polymarket/activity

Polymarket

List trade activity for a configured polygon-mainnet Polymarket wallet.

Polymarket Open Positions

Auth Required

GET

/api/agent/venues/polymarket/positions

Polymarket

List open Polymarket positions for a configured polygon-mainnet wallet. Response is filtered to open markets and includes position PnL fields.

Polymarket Redeemable Positions

Auth Required

GET

/api/agent/venues/polymarket/redeemable

Polymarket

List currently redeemable Polymarket positions for a configured polygon-mainnet wallet. Use returned tokenId values for single-position redeem.

Redeem Polymarket Positions

Auth Required

POST

/api/agent/venues/polymarket/redeem

Polymarket

Redeem resolved Polymarket positions for a configured polygon-mainnet wallet. The server picks the signing path from the wallet's configured signatureType:

0: signs directly on-chain from the wallet's EOA (user pays a few cents of POL for gas).
1 / 2: redeems through Polymarket's gasless relayer using API credentials.

Pass tokenId to redeem one position, or omit it to redeem all redeemable positions. Optional signatureType defensively asserts which signing path the wallet must be configured for; a mismatch returns 400.

YieldWolf Casino

4 endpoints

Link YieldWolf Casino

Auth Required

POST

/api/agent/venues/yieldwolf-casino/link

YieldWolf Casino

Bind a Solana wallet to a YieldWolf Casino account. The linked wallet is the only allowed withdrawal destination.

Lane: real = solana-mainnet, test = solana-devnet/testnet. Fixed at link time.
Response: returns a proxy_base and an instructions payload that names every gameplay flow. Subsequent casino calls go through the proxy so OpenClawCash can enforce scope and audit every action.
The raw casino key is intentionally not returned to the agent.

HTTP Request

POST /api/agent/venues/yieldwolf-casino/link

Request Parameters / Body

1{
2  "walletId": "Q7X2K9P",
3  "agentName": "treasury-agent",
4  "lane": "real"
5}

Request Example

1curl -X POST https://your-app.vercel.app/api/agent/venues/yieldwolf-casino/link \
2  -H "Content-Type: application/json" \
3  -H "X-Agent-Key: occ_your_api_key" \
4  -d '{
5    "walletId": "Q7X2K9P",
6    "lane": "real"
7  }'

Response Example

1{
2  "venue": "yieldwolf-casino",
3  "walletId": "Q7X2K9P",
4  "network": "solana-mainnet",
5  "status": "linked",
6  "agentId": "yw_agent_...",
7  "lane": "real",
8  "proxy_base": "/api/agent/venues/yieldwolf-casino/proxy",
9  "instructions": {
10    "skill_doc": "https://yieldwolf.finance/SKILL.md",
11    "summary": "All casino calls route through OCC's proxy at proxy_base...",
12    "flows": {
13      "fund": "...",
14      "balance": "GET {proxy_base}/agents/me/balance",
15      "catalog": "...",
16      "play_standard": "...",
17      "play_kuhn": "...",
18      "history": "...",
19      "withdraw": "...",
20      "agentwatch": "..."
21    },
22    "responsible_play": [
23      "Cap any single bet at <= 2% of available balance",
24      "Stop-loss at -10% session drawdown",
25      "Reserve >= 20% of balance (do not wager reserve)"
26    ],
27    "lane_note": "...",
28    "credential_note": "..."
29  }
30}

Unlink YieldWolf Casino

Auth Required

POST

/api/agent/venues/yieldwolf-casino/unlink

YieldWolf Casino

Clear the YieldWolf Casino binding for a linked wallet. To switch lanes (real <-> test), unlink and re-link.

Casino Gateway Read

Auth Required

GET

/api/agent/venues/yieldwolf-casino/proxy/{upstreamPath}

YieldWolf Casino

Read passthrough to YieldWolf's gateway. The path after /proxy/ is the YieldWolf path you want to call (like agents/me/balance or transactions/history).

Wallet: pass the linked wallet via ?walletId= or ?walletAddress= (exactly one).
Auth and scope: OpenClawCash injects the casino auth header server-side, enforces the read venue scope, and logs every call.

Writes use Casino Gateway Write.

Casino Gateway Write

Auth Required

POST

/api/agent/venues/yieldwolf-casino/proxy/{upstreamPath}

YieldWolf Casino

Write passthrough to YieldWolf's gateway. The path after /proxy/ is the YieldWolf path you want to call (multi-segment paths like games/play or transactions/withdraw are accepted).

Wallet: pass the linked wallet via ?walletId= or ?walletAddress=.
Auth and scope: OpenClawCash injects the casino auth header server-side, enforces the trade venue scope for writes, and logs every call.
Retries: pass an X-Idempotency-Key header on writes to make retries safe.

Reads use Casino Gateway Read. See yieldwolf.finance/SKILL.md for the full upstream surface.

Ready to Build with OpenClawCash?

Start using our API to create wallets, handle transfers, and manage policies for your AI agents.