---
name: mach-base
displayName: MACH Base
description: >-
  Use MACH Base when an agent needs current Base mainnet state: block and gas data,
  wallet or token balances, transaction receipts/details, event logs, contract reads,
  token supply, contract introspection, or ERC-20 transfer history.
version: 1.0.0
author: MACH
type: API
pricingModel: fixed
category: blockchain-data
tags:
  - base
  - blockchain
  - onchain
  - x402
  - usdc
  - wallet
  - erc20
  - contract
  - transaction
base_url: https://api.mach.gallery
mcp_server: https://api.mach.gallery/mcp
openapi: https://api.mach.gallery/openapi.json
manifest: https://api.mach.gallery/.well-known/x402
contact: api@mach.gallery
payment:
  asset: USDC
  networks:
    - network: base
      payTo: 0xB6313D094618b20dd29994Bec6697aE1e9F02DfE
      facilitator: https://facilitator.openx402.ai
endpoints:
  - path: /api/base/block-number
    method: GET
    description: Return the current Base mainnet block number
    priceUsdc: "0.001"
  - path: /api/base/gas-price
    method: GET
    description: Return the current Base gas price in wei
    priceUsdc: "0.001"
  - path: /api/base/wallet-balance
    method: POST
    description: Read native ETH balance for one Base address
    priceUsdc: "0.003"
  - path: /api/base/erc20-balance
    method: POST
    description: Read an ERC-20 balance for one Base wallet
    priceUsdc: "0.003"
  - path: /api/base/nonce
    method: POST
    description: Return the transaction nonce for one Base address
    priceUsdc: "0.003"
  - path: /api/base/contract-code
    method: POST
    description: Check whether an address is a deployed contract and return bytecode size
    priceUsdc: "0.003"
  - path: /api/base/allowance
    method: POST
    description: Read an ERC-20 allowance for owner and spender
    priceUsdc: "0.003"
  - path: /api/base/receipt
    method: POST
    description: Return transaction receipt and confirmation depth
    priceUsdc: "0.005"
  - path: /api/base/logs
    method: POST
    description: Query bounded Base contract event logs
    priceUsdc: "0.005"
  - path: /api/base/eth-call
    method: POST
    description: Execute a read-only eth_call on Base
    priceUsdc: "0.005"
  - path: /api/base/transaction
    method: POST
    description: Return a Base transaction by hash
    priceUsdc: "0.008"
  - path: /api/base/block
    method: POST
    description: Return a Base block header and transaction hashes
    priceUsdc: "0.003"
  - path: /api/base/wallet-snapshot
    method: POST
    description: Read native ETH plus up to ten caller-supplied ERC-20 balances
    priceUsdc: "0.003"
  - path: /api/base/total-supply
    method: POST
    description: Read totalSupply for an ERC-20 or ERC-721 contract
    priceUsdc: "0.003"
  - path: /api/base/contract-info
    method: POST
    description: Inspect contract bytecode and best-effort token metadata/interfaces
    priceUsdc: "0.005"
  - path: /api/base/erc20-transfers
    method: POST
    description: Query bounded ERC-20 Transfer events with optional wallet filters
    priceUsdc: "0.005"
---

# MACH Base

MACH Base provides live Base mainnet data for autonomous agents. Use it when the task needs current
onchain state rather than a cached answer. There is no buyer account, API key, subscription, or
minimum spend. Each call is paid independently in USDC over x402.

## Fastest integration

For MCP-capable agents, connect directly to:

`https://api.mach.gallery/mcp`

Transport: **Streamable HTTP**. The server exposes the same 16 paid capabilities as MCP tools and
returns x402 payment requirements when a paid tool is called without a payment.

For direct HTTP integration, start with the catalog:

`GET https://api.mach.gallery/api/catalog`

Machine discovery:
- x402 manifest: `https://api.mach.gallery/.well-known/x402`
- OpenAPI: `https://api.mach.gallery/openapi.json`
- MCP: `https://api.mach.gallery/mcp`
- health: `https://api.mach.gallery/health`

## Payment protocol

MACH Base uses **x402 v2** on Base mainnet.

1. Make the intended HTTP request normally.
2. An unpaid paid route responds with HTTP `402 Payment Required`.
3. Read the Base64-encoded `PAYMENT-REQUIRED` response header. It contains the x402 v2 envelope,
   accepted payment requirement, exact USDC amount, Base network, recipient, resource metadata,
   and Bazaar discovery metadata.
4. Sign the required payment authorization in the buyer wallet.
5. Retry the same request with the signed payment in the `PAYMENT-SIGNATURE` header.
6. On successful verification/settlement, MACH returns the requested result and a
   `PAYMENT-RESPONSE` header.

Do not treat the initial 402 as an application error. It is the normal price-quote step.

## Choosing a tool

Use the cheapest tool that answers the question.

| Need | Tool / route | Price |
| --- | --- | ---: |
| Current chain height | `base_block_number` / `GET /api/base/block-number` | $0.001 |
| Current gas price | `base_gas_price` / `GET /api/base/gas-price` | $0.001 |
| Native wallet balance | `base_wallet_balance` | $0.003 |
| ERC-20 wallet balance | `base_erc20_balance` | $0.003 |
| Wallet nonce | `base_nonce` | $0.003 |
| Contract bytecode check | `base_contract_code` | $0.003 |
| Token allowance | `base_allowance` | $0.003 |
| Block details | `base_block` | $0.003 |
| Wallet + token snapshot | `base_wallet_snapshot` | $0.003 |
| Token total supply | `base_total_supply` | $0.003 |
| Receipt + confirmations | `base_receipt` | $0.005 |
| Event logs | `base_logs` | $0.005 |
| Read-only contract call | `base_eth_call` | $0.005 |
| Contract/token introspection | `base_contract_info` | $0.005 |
| ERC-20 transfer events | `base_erc20_transfers` | $0.005 |
| Full transaction | `base_transaction` | $0.008 |

## Common calls

### Current block number

`GET /api/base/block-number`

No request body.

### Native wallet balance

`POST /api/base/wallet-balance`

```json
{"address":"0x0000000000000000000000000000000000000001"}
```

### ERC-20 balance

`POST /api/base/erc20-balance`

```json
{
  "token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "address":"0x0000000000000000000000000000000000000001"
}
```

### Wallet snapshot

Use this instead of several separate balance calls when the caller already knows which token
contracts matter. Up to ten token contracts can be supplied.

`POST /api/base/wallet-snapshot`

```json
{
  "address":"0x0000000000000000000000000000000000000001",
  "tokens":["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"]
}
```

### Transaction receipt

`POST /api/base/receipt`

```json
{"tx_hash":"0x0000000000000000000000000000000000000000000000000000000000000000"}
```

Use this when the important question is whether a transaction succeeded and how deeply it is
confirmed. Use `base_transaction` when the request needs the transaction payload itself.

### Contract information

`POST /api/base/contract-info`

```json
{"address":"0x4200000000000000000000000000000000000006"}
```

This is best-effort introspection. A contract is not required to implement token metadata methods.

### ERC-20 transfers

`POST /api/base/erc20-transfers`

```json
{
  "token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "from_block":35999000,
  "to_block":36000000
}
```

Optional `from_address` and `to_address` filters can narrow results. Block ranges are bounded to
protect both buyer latency and provider reliability.

### Generic read-only contract call

`POST /api/base/eth-call`

```json
{
  "to":"0x4200000000000000000000000000000000000006",
  "data":"0x",
  "block":"latest"
}
```

Use this only when the caller already knows the ABI calldata. Prefer a specific MACH tool when one
exists because the specific tools have clearer schemas and lower chances of a malformed call.

## Agent workflow

1. Determine exactly which live Base fact is needed.
2. Prefer the lowest-cost specific tool that returns that fact.
3. If several balances are needed for one wallet, use `base_wallet_snapshot` rather than separate calls.
4. Make the call and handle the x402 v2 payment challenge.
5. Return the MACH result as live onchain data; do not silently replace failed calls with guessed values.
6. For repeat workflows, cache immutable transaction/block results locally when appropriate instead of buying the same historical fact again.

## Error handling

- `402`: normal x402 payment challenge. Pay and retry when the buyer authorizes the spend.
- `422`: malformed or unsupported request. Correct the payload; do not pay/retry unchanged.
- `429`: rate limiting. Back off before retrying.
- `5xx`: transient provider/server failure. Retry once after a short delay, then surface the failure.
- Missing transaction/receipt: a valid result can be `found: false`; do not invent a transaction.

## Trust and verification

MACH publishes its live catalog, OpenAPI definition, x402 manifest, health endpoint, contact
addresses and MCP endpoint on the same canonical origin. Discovery metadata includes examples,
schemas, service name and icon. Reliability and usage should be judged from live directory and
settlement evidence rather than marketing claims.

Provider: **MACH**  
Service: **MACH Base**  
Contact: **api@mach.gallery**