BEAM·v0.1.1·MACOS · LINUX·SHA-256 VERIFIED
DOCS/Commands/fetch

fetch

Built-in HTTP client that can also satisfy x402 and MPP payment challenges with your active Beam wallet.

beam fetch is a curl-style HTTP client. It makes the initial request directly from Rust, prints the response body to stdout by default, and — when a server answers with 402 Payment Required — pays from the active Beam wallet and retries the original request transparently.

Common usage

$ beam fetch https://api.example.com/data
$ beam fetch -X POST -H "Content-Type: application/json" -d '{"key":"value"}' \
  https://api.example.com/submit
$ beam fetch -o response.json https://api.example.com/data
$ beam fetch -v -L https://api.example.com/redirect

Request flags

Flag Purpose
-X, --method <METHOD> Override the HTTP method. Without -X, Beam defaults to GET, or POST when -d / --data / --data-file is present.
-H, --header <NAME: VALUE> Attach a request header. Repeat for multiple headers.
-d, --data <BODY> Send <BODY> as the request body.
--data-file <PATH> Send the contents of <PATH> as the request body.
-o, --output <PATH> Write the response body to a file instead of stdout.
-v, --verbose Print request and response headers to stderr. Beam redacts sensitive request header values (Authorization, Cookie, payment credentials) before printing.
-L, --follow-redirects Follow same-origin redirects only. Cross-origin hops are stopped to avoid replaying origin-scoped headers.
--max-redirects <N> Cap on redirect hops when -L is set.
--connect-timeout <SECONDS> Connection timeout.
--timeout <SECONDS> Total request timeout.

Payment flags

Flag Purpose
--no-pay Print the payment challenge and exit without signing.
--max-fee <AMOUNT> Auto-confirm only when the estimated total stays at or below the cap. See Fee caps.
--allowed-chains <NAME|ID>[,...] Auto-approve only those destination chains. See Chain allowlists.
--private-payment Require a privacy-capable challenge and satisfy it with a private transfer on the selected privacy-capable chain.
--dev Allow plain HTTP payment challenges only for localhost or loopback. Beam otherwise refuses to pay a 402 over plain HTTP.

Payment flow

  • Use --from <wallet|address|ens> to choose which stored wallet pays.
  • Use --chain <name|id> to force x402 offer selection. For MPP, it's an explicit constraint — if the challenge already includes a different chainId, Beam fails instead of prompting.
  • --chain and --allowed-chains accept the same selectors as other Beam chain commands, including canonical names, numeric ids, and aliases (eth, bsc, arb, payydev).
  • MPP challenges that omit a chain are rejected unless you explicitly provide --chain or --rpc.
  • MPP problem responses must include a valid WWW-Authenticate: Payment ... challenge. Malformed MPP responses are rejected on both the paid and --no-pay paths.
  • When a payment targets a different chain than your selected/default chain, Beam prompts for confirmation unless --allowed-chains explicitly permits it.
  • Payment challenges served over plain HTTP are rejected unless you opt into --dev and the URL stays on localhost or loopback.

Retry behavior

  • x402: Beam retries the original request with a Beam-generated payment-proof header after the on-chain payment confirms.
  • MPP: Beam retries with an Authorization: Payment ... credential after the payment confirms. If the original same-origin request already set Authorization, Beam fails instead of overwriting the caller-supplied credential.
  • Same-origin redirects pre-402: If a 302 / 303 rewrites the request before the 402 response (e.g. POST → GET), Beam retries the effective challenged request after payment, not the pre-redirect method and body.

Private payments

$ beam --from alice --chain payy-testnet fetch \
  --private-payment https://paywall.example/article/123

--private-payment rejects ordinary public challenges and only returns payment credentials after the private transfer confirms. The same private send flow as beam privacy send handles the payment.

Interrupting safely

In the REPL, once beam fetch starts the on-chain payment transaction, Ctrl-C stops waiting for confirmation without losing the submitted hash. After the transaction phase, Ctrl-C again cancels the paid retry request or response download and returns to the prompt.

Examples

$ beam fetch --max-fee 0.001 https://paywall.example/article/123
$ beam fetch --allowed-chains base,8453 https://paywall.example/article/123
$ beam fetch --no-pay https://paywall.example/article/123
$ beam --from alice --chain base fetch \
  --max-fee 0.001 https://paywall.example/article/123
$ beam --from alice --chain payy-testnet fetch \
  --private-payment https://paywall.example/article/123
$ beam fetch -v -L https://api.example.com/redirect
◂ Previoussend