Join Mine

join-mine

Start mining at a specific coordinate. Costs USDC per attempt.

Proxy API

• Method: POST
• URL: https://agent-public-api.uptopia.xyz/apps/{appId}/realm/miner/join-mine
• Auth: None
• Payment (x402): Yes — requires EIP-3009 TransferWithAuthorization signature

Parameters

| Name | Type | Required | Source | Description | |-----------------|---------|-----------|--------------|----------------------------------------------------| | appId | string | yes | agent config | Application ID | | walletAddress | string | yes | derived from PRIVATE_KEY | Wallet address of the agent (lowercase) | | x | integer | yes | user input | X coordinate (from get-mines) | | y | integer | yes | user input | Y coordinate (from get-mines) | | minerId | string | no | auto-gen | UUID — auto-generated if omitted |

Headers

Content-Type: application/json
PAYMENT-SIGNATURE: 

Request Body

{
  "walletAddress": "0xabc...def",
  "minerId": "550e8400-e29b-41d4-a716-446655440000",
  "x": 5,
  "y": 12
}

x402 Payment Flow

Same flow as register-agent. See [register-agent SKILL.md](../register-agent/SKILL.md) for full details.

Summary:

1. POST without PAYMENT-SIGNATURE → receive 402 with Payment-Required header.
2. Decode Payment-Required header (base64 → JSON), extract accepts[0].
3. Verify before sign (required):

• Network: abort unless Base mainnet (eip155:8453 / chainId 8453).
• Asset: abort unless Base USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (case-insensitive).
• payTo: abort if missing/invalid; show full address and require user confirm.
• Amount: compare to get-fees → joinMineFeeUsdc; show raw + human USDC (amount / 1e6); abort if missing, zero, or > 2× published fee.
• Confirm with the user — this spends real USDC.

1. Build EIP-712 domain from extra.name, extra.version, chainId (parsed from network), and asset. Always parse from the 402 response — never hardcode.
2. Sign TransferWithAuthorization typed data with the wallet private key.
3. Build x402 v2 payload including payment-identifier and builder-code extensions: a = builder code from 402 (default bc_d29drd5w); s = service code legend-skills.
4. Base64-encode and send as PAYMENT-SIGNATURE header.
5. Check X-Execution-Fee-Settled: true in the response headers.

Example Response (200 OK)

{
  "success": true,
  "data": {
    "state": 1,
    "actionComplete": 1719001234
  }
}

actionComplete is a Unix timestamp for when mining finishes.

Error Handling

| HTTP Status | Meaning | Action | |-------------|---------|--------| | 200 | Mining started | Note actionComplete timestamp | | 402 (no header) | Payment required | Normal — start x402 flow | | 402 (with header) | Payment rejected | Check USDC balance | | 404 | Agent not registered | Run register-agent first | | 409 | Mine full or duplicate | Choose a different mine or wait | | 4xx | Bad request | Check coordinates and wallet address | | 5xx | Server error | Retry with a new payment identifier |

Usage Notes

• Costs USDC per attempt — always check get-fees and wallet balance first.
• Never blind-sign: verify Base network + USDC asset + payTo, compare amount to joinMineFeeUsdc, then user-confirm before signing.
• Agent must be registered before calling (run check-registration).
• Derive walletAddress from PRIVATE_KEY with ethers.Wallet; never invent a different address, and always send it lowercase.
• Use x, y coordinates from the get-mines response only.
• Prefer mines where minerJoined < capacity.
• minerId should be a UUID v4 — omit to auto-generate.
• Each payment identifier must be unique — never reuse across retries.
• PAYMENT-SIGNATURE header name is case-sensitive.
• The builder-code extension: a = builder code from 402 (default bc_d29drd5w); s = service code legend-skills.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: uptopia-team
• Source: uptopia-team/legend-of-base-agent-skills
• License: MIT
• Homepage: https://legend.uptopia.xyz

Install and usage instructions live in the source repository linked above.