agent-dlocal
dLocal payment triage CLI for AI agents
- Language
- Go
- Version
- 0.2.1
- License
- PolyForm Perimeter 1.0.0
- Category
- CLI Tool
A read-only investigation CLI over dLocal, the emerging-markets payment processor covering LatAm, Africa and Asia. It turns "why did this payment fail?", "where did this payout go?" and "what happened to this refund?" into single commands that return a verdict, whether the state is final, the evidence behind it and what to do next — with national ID numbers redacted and credentials never in view.
Features
investigate returns a verdict, not a dump — plus a terminal flag saying whether the state is final, next_steps, and the evidence it drew on
Read-only by construction — every command is a GET and the raw api group has no --method flag; the guarantee is an absent code path, not a check
Reads the status triple properly — status, status_code and status_detail disagree in useful ways, and the detail carries the reason
Calls out DELIVERED — a payout status that is neither final nor a failure, and the one most often misread
Merchant order_id resolves to a dLocal payment — the "they say they paid, our order says unpaid" question, answered directly
Multi-market in one call — payment-methods list PH VN TH returns one record per country, in input order
Market discovery without an endpoint — countries probes all 43 markets in about a second, since dLocal has no list-countries API
payer.document redacted by default — CPF, CUIT and DNI are national ID numbers; --expose opts out per invocation
Native OS dialogs per secret — X-Login, X-Trans-Key and the secret key go keyboard-to-keychain, one titled dialog each
Live vs sandbox is recorded, never guessed — dLocal keys carry no test/live marker, so it is an explicit host distinction on the profile
Optional mutual TLS — --cert/--key take paths, and the files stay under your own permissions
Install
Homebrew
$ brew install shhac/tap/agent-dlocal AI Agent Skill
$ npx skills add shhac/agent-skills --skill agent-dlocal --global GitHub Release (macOS)
$ curl -L https://github.com/shhac/agent-dlocal/releases/latest/download/agent-dlocal-darwin-arm64.tar.gz | tar xz Go Install
$ go install github.com/shhac/agent-dlocal/cmd/agent-dlocal@latest Build from Source
$ git clone https://github.com/shhac/agent-dlocal.git && cd agent-dlocal && make build Getting Started
agent-dlocal needs three secrets — X-Login, X-Trans-Key and a secret key. Because dLocal keys carry no test/live marker, sandbox is an explicit flag on the profile rather than something inferred from the credential.
01 · Add a profile through native OS dialogs
$ agent-dlocal auth add prod --form One dialog per secret, each titled with the value it wants, so all three go straight from your keyboard into the OS keychain. --login/--trans-key/--secret-key exist for automation.
02 · Add a sandbox profile alongside it
$ agent-dlocal auth add sbox --sandbox --form Live vs sandbox is a host distinction recorded on the profile, never guessed from the key.
03 · Confirm the credential works
$ agent-dlocal auth check 403 with code 3001 comes back before the signature is checked — that means the caller was rejected outright, usually an IP allowlist or a wrong-host profile.
04 · Start from the question
$ agent-dlocal investigate payment D-4-8f2a Returns a verdict, a terminal flag, next_steps and the evidence. agent-dlocal usage prints the whole map.
Usage
$ agent-dlocal investigate payment D-4-8f2a $ agent-dlocal investigate order ORDER-10241 $ agent-dlocal investigate payout P-2-91bc $ agent-dlocal payments get D-4-aaa D-4-bbb $ agent-dlocal payment-methods list PH VN TH $ agent-dlocal payment-methods countries --supported $ agent-dlocal api get /payments/D-4-aaa