Sign & Submit API
Synchronous endpoints for signing messages and submitting transactions directly — no polling required.
Overview
| Endpoint | Purpose | Returns |
|---|---|---|
POST /agent/sign | Sign messages, typed data, or transactions | Signature |
POST /agent/submit | Submit raw transactions to chain | Transaction hash |
Unlike /agent/prompt (async with job polling), these endpoints return immediately.
POST /agent/sign
Sign data without broadcasting to the network.
Signature Types
| Type | Use Case |
|---|---|
personal_sign | Sign plain text messages (auth, verification) |
eth_signTypedData_v4 | Sign EIP-712 typed data (permits, orders) |
eth_signTransaction | Sign transactions for later broadcast |
Prompt Examples
Sign a message:
- "Sign this message: Hello World"
- "Sign in to MyApp with nonce abc123"
Sign typed data (EIP-712 permit):
- "Sign this EIP-712 permit for USDC approval"
Sign a transaction without broadcasting:
- "Sign this transaction but don't send it"
Success Response
{
"success": true,
"signature": "0x...",
"signer": "0xYourWalletAddress",
"signatureType": "personal_sign"
}
Common Errors
| Status | Error | Cause |
|---|---|---|
| 400 | Missing required field | Missing message, typedData, or transaction |
| 401 | Authentication required | Missing or invalid API key |
| 403 | Read-only API key | Key lacks write permissions |
POST /agent/submit
Submit raw transactions directly to the blockchain.
Transaction Fields
| Field | Required | Description |
|---|---|---|
to | Yes | Destination address |
chainId | Yes | Chain ID (8453=Base, 1=Ethereum, 137=Polygon) |
value | No | Value in wei (as string) |
data | No | Calldata (hex string) |
gas | No | Gas limit |
waitForConfirmation | No | Wait for on-chain confirmation (default: true) |
Prompt Examples
Submit a raw transaction:
- "Submit this transaction on Base: {to: 0x..., data: 0x..., value: 0}"
Simple ETH transfer:
- "Submit a transfer of 1 ETH to 0x..."
Success Response
With confirmation:
{
"success": true,
"transactionHash": "0x...",
"status": "success",
"blockNumber": "12345678",
"gasUsed": "21000",
"signer": "0xYourWalletAddress",
"chainId": 8453
}
Transaction Status Values
| Status | Description |
|---|---|
success | Confirmed and succeeded |
reverted | Confirmed but reverted |
pending | Submitted, not yet confirmed |
Use Cases
- Authentication: Sign messages to verify wallet ownership
- Gasless approvals: Sign EIP-2612 permits without gas
- Pre-built transactions: Submit calldata from external tools
- Multi-step workflows: Execute approve + swap in sequence
Comparison with /agent/prompt
| Feature | /agent/prompt | /agent/sign | /agent/submit |
|---|---|---|---|
| Input | Natural language | Structured data | Transaction object |
| Response | Async (job ID) | Sync (signature) | Sync (tx hash) |
| Executes on-chain | Via AI agent | No | Yes |
| Best for | General queries | Auth, permits | Raw transactions |
Security Notes
/agent/submitexecutes immediately with no confirmation prompt- Validate all transaction parameters before submission
- Use
waitForConfirmation: truefor important transactions - Read-only API keys cannot use these endpoints (403)