{
	"title": "Agent Quickstart — Create a Payment Intent",
	"description": "Minimal instructions for an AI agent to create payment intents (transfers and Polymarket trades) using a JSON credential file.",
	"baseUrl": "https://www.agentintents.io",
	"prerequisites": ["Foundry (cast)", "curl", "jq"],
	"credentialFile": {
		"description": "JSON credential file generated when the human owner registers your agent from the web UI.",
		"schema": {
			"version": 1,
			"label": "My Agent",
			"trustchainId": "0x<owner-wallet-address>",
			"privateKey": "0x<hex-encoded-secp256k1-private-key>",
			"publicKey": "0x<hex-encoded-compressed-public-key>",
			"createdAt": "2026-01-01T00:00:00.000Z"
		},
		"security": "Never commit this file. The privateKey field is a secret."
	},
	"authentication": {
		"headerFormat": "Authorization: AgentAuth <timestamp>.<bodyHash>.<signature>",
		"parts": {
			"timestamp": "Current Unix epoch in seconds as a string. Must be within 5 minutes of server time.",
			"bodyHash": "keccak256 of the raw JSON body as 0x-prefixed hex string. For GET requests use the literal string '0x'.",
			"signature": "EIP-191 personal_sign of '<timestamp>.<bodyHash>' using the agent's privateKey. Must be 0x-prefixed."
		},
		"bodyHashing": "The bodyHash is computed over the exact bytes sent in the request body. Use compact JSON (no extra whitespace) to ensure a deterministic hash."
	},
	"createTransferIntent": {
		"method": "POST",
		"url": "https://www.agentintents.io/api/intents",
		"headers": {
			"Content-Type": "application/json",
			"Authorization": "AgentAuth <timestamp>.<bodyHash>.<signature>"
		},
		"body": {
			"agentId": "my-agent",
			"agentName": "My Agent",
			"details": {
				"type": "transfer",
				"token": "USDC",
				"amount": "1.00",
				"recipient": "0xRecipientAddress",
				"chainId": 8453,
				"memo": "Reason for payment"
			},
			"urgency": "normal",
			"expiresInMinutes": 60
		},
		"exampleResponse": {
			"success": true,
			"intent": {
				"id": "int_1770399036079_804497de",
				"userId": "0x20bfb083c5adacc91c46ac4d37905d0447968166",
				"agentId": "my-agent",
				"agentName": "My Agent",
				"details": {
					"type": "transfer",
					"token": "USDC",
					"amount": "1.00",
					"recipient": "0xRecipientAddress",
					"chainId": 8453,
					"memo": "Reason for payment"
				},
				"urgency": "normal",
				"status": "pending",
				"trustChainId": "0x20bfb083c5adacc91c46ac4d37905d0447968166",
				"createdAt": "2026-02-06T17:30:36.127Z",
				"expiresAt": "2026-02-06T18:30:36.080Z",
				"statusHistory": [{ "status": "pending", "timestamp": "2026-02-06T17:30:36.222Z" }]
			},
			"paymentUrl": "https://www.agentintents.io/pay/int_1770399036079_804497de"
		},
		"nextStep": "Share the paymentUrl with the human so they can review and sign the transaction."
	},
	"searchPolymarketMarkets": {
		"method": "GET",
		"url": "https://www.agentintents.io/api/polymarket/markets",
		"description": "Search for active Polymarket markets by keyword. No authentication required. Use this to find the conditionId before creating a polymarket_trade intent.",
		"parameters": {
			"q": { "type": "string", "default": "", "description": "Search keyword (e.g. 'bitcoin', 'trump', 'ethereum')" },
			"limit": { "type": "number", "default": 10, "min": 1, "max": 50, "description": "Max results" }
		},
		"exampleRequest": "GET https://www.agentintents.io/api/polymarket/markets?q=bitcoin&limit=5",
		"exampleResponse": {
			"success": true,
			"markets": [
				{
					"conditionId": "0xabc123...",
					"question": "Will Bitcoin hit $100k by July 2026?",
					"yesPrice": 0.65,
					"noPrice": 0.35,
					"volume": 1250000,
					"endDate": "2026-07-01T00:00:00.000Z",
					"active": true
				}
			]
		}
	},
	"createPolymarketIntent": {
		"method": "POST",
		"url": "https://www.agentintents.io/api/intents",
		"headers": {
			"Content-Type": "application/json",
			"Authorization": "AgentAuth <timestamp>.<bodyHash>.<signature>"
		},
		"description": "Create a Polymarket trade intent. The backend enriches it with marketTitle and outcomePrice from the Gamma API.",
		"body": {
			"agentId": "my-agent",
			"agentName": "My Agent",
			"details": {
				"type": "polymarket_trade",
				"conditionId": "0xabc123...",
				"outcome": "Yes",
				"amount": "50",
				"chainId": 137,
				"memo": "Agent's justification for the trade"
			},
			"urgency": "normal",
			"expiresInMinutes": 60
		},
		"fields": {
			"type": { "required": true, "description": "Must be 'polymarket_trade'" },
			"conditionId": { "required": true, "description": "Polymarket condition ID from search endpoint" },
			"outcome": { "required": true, "description": "'Yes' or 'No'" },
			"amount": { "required": true, "description": "Amount in USDC (e.g. '50', '100.50')" },
			"chainId": { "required": true, "description": "Must be 137 (Polygon)" },
			"memo": { "required": false, "description": "Agent's justification for the trade (shown to the human)" }
		},
		"exampleResponse": {
			"success": true,
			"intent": {
				"id": "int_1770399099999_def456ab",
				"userId": "0x20bfb083c5adacc91c46ac4d37905d0447968166",
				"agentId": "my-agent",
				"agentName": "My Agent",
				"details": {
					"type": "polymarket_trade",
					"conditionId": "0xabc123...",
					"marketTitle": "Will Bitcoin hit $100k by July 2026?",
					"outcome": "Yes",
					"amount": "50",
					"outcomePrice": 0.65,
					"chainId": 137,
					"memo": "Agent's justification for the trade"
				},
				"urgency": "normal",
				"status": "pending",
				"trustChainId": "0x20bfb083c5adacc91c46ac4d37905d0447968166",
				"createdAt": "2026-02-06T17:35:00.000Z",
				"expiresAt": "2026-02-06T18:35:00.000Z",
				"statusHistory": [{ "status": "pending", "timestamp": "2026-02-06T17:35:00.000Z" }]
			},
			"paymentUrl": "https://www.agentintents.io/pay/int_1770399099999_def456ab"
		},
		"nextStep": "Share the paymentUrl with the human so they can review the trade and sign with their Ledger."
	},
	"pollForCompletion": {
		"method": "GET",
		"url": "https://www.agentintents.io/api/intents/<intent-id>",
		"headers": {
			"Authorization": "AgentAuth <timestamp>.0x.<signature>"
		},
		"terminalStatuses": ["confirmed", "rejected", "failed", "expired"],
		"description": "Poll until status is one of the terminal states. Works for both transfer and polymarket_trade intents."
	},
	"supportedChains": [
		{ "chainId": 8453, "name": "Base", "token": "USDC", "notes": "Mainnet" },
		{ "chainId": 84532, "name": "Base Sepolia", "token": "USDC", "notes": "Testnet" },
		{ "chainId": 11155111, "name": "Sepolia", "token": "USDC", "notes": "Testnet" },
		{ "chainId": 137, "name": "Polygon", "token": "USDC", "notes": "Polymarket trades only" }
	],
	"troubleshooting": [
		{
			"error": "401 Authentication failed",
			"cause": "Signature or body hash is malformed",
			"fix": "Ensure bodyHash and signature are 0x-prefixed hex strings"
		},
		{
			"error": "401 Authentication failed",
			"cause": "Timestamp drift",
			"fix": "Ensure your system clock is accurate (within 5 minutes of server time)"
		},
		{
			"error": "401 Authentication failed",
			"cause": "Body hash mismatch",
			"fix": "Ensure you hash the exact bytes sent as the request body (compact JSON, no trailing newline)"
		},
		{
			"error": "400 Market not found",
			"cause": "Invalid conditionId",
			"fix": "Use the search endpoint (GET /api/polymarket/markets?q=...) to find valid condition IDs"
		},
		{
			"error": "400 Market is no longer active",
			"cause": "Market has closed or expired",
			"fix": "Search for a different active market"
		}
	],
	"links": {
		"webUI": "https://www.agentintents.io",
		"apiDocs": "https://www.agentintents.io/docs",
		"openAPISpec": "https://www.agentintents.io/openapi.json",
		"agentContextPage": "https://www.agentintents.io/agent-context",
		"agentContextJSON": "https://www.agentintents.io/agent-context.json"
	}
}